@zlink-systems/nestjs 0.10.0

package/dist/options-builder.js

@@ -0,0 +1,973 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createZLinkNestFrameworkOptionsBuilder = createZLinkNestFrameworkOptionsBuilder;
+const framework_1 = require("@zlink-systems/framework");
+const contracts_1 = require("./contracts");
+const framework_loader_1 = require("./framework-loader");
+function createBuilderState() {
+    const codecOptions = { serializers: [], streamCodecs: [] };
+    return {
+        additionalOptions: {},
+        implicitHandlerAutoRegistration: true,
+        clientServerChannels: {},
+        fanoutChannels: {},
+        streams: {},
+        spotNodes: {},
+        codecOptions,
+        codecRegistry: framework_loader_1.framework.createIntegrationCodecRegistryBuilder(codecOptions)
+    };
+}
+function registerSerializer(state, contentType, serializer, canSerialize) {
+    if (canSerialize === undefined) {
+        state.codecRegistry.addSerializer(contentType, serializer);
+    }
+    else {
+        state.codecRegistry.addSerializer(contentType, serializer, canSerialize);
+    }
+}
+function registerStreamCodec(state, contentType, codec) {
+    state.codecRegistry.addStreamCodec(contentType, codec);
+}
+function ensureChannelAvailable(state, name) {
+    if (name.trim().length === 0 || name.trim() !== name) {
+        throw new framework_loader_1.framework.ZLinkConfigurationException('Channel name must not be empty or padded.');
+    }
+    if (Object.prototype.hasOwnProperty.call(state.fanoutChannels, name)
+        || Object.prototype.hasOwnProperty.call(state.clientServerChannels, name)) {
+        throw new framework_loader_1.framework.ZLinkConfigurationException(`Duplicate channel '${name}'.`);
+    }
+}
+function ensureClientServerChannelAvailable(state, name) {
+    if (name.trim().length === 0 || name.trim() !== name) {
+        throw new framework_loader_1.framework.ZLinkConfigurationException('Channel name must not be empty or padded.');
+    }
+    if (Object.prototype.hasOwnProperty.call(state.fanoutChannels, name)) {
+        throw new framework_loader_1.framework.ZLinkConfigurationException(`Duplicate channel '${name}'.`);
+    }
+}
+class ZLinkNestOptionsBuilder {
+    state;
+    constructor(state) {
+        this.state = state;
+    }
+    options(options) {
+        this.state.additionalOptions = { ...this.state.additionalOptions, ...options };
+        return this;
+    }
+    disableImplicitHandlerAutoRegistration() {
+        this.state.implicitHandlerAutoRegistration = false;
+        return this;
+    }
+    codecs() {
+        return new DefaultZLinkNestCodecRegistryBuilder(this.state);
+    }
+    configureDispatch() {
+        this.state.additionalOptions = {
+            ...this.state.additionalOptions,
+            dispatch: this.state.additionalOptions.dispatch ?? {
+                unhandled: {
+                    request: framework_1.ZLinkUnhandledDispatchAction.ReplyError,
+                    send: framework_1.ZLinkUnhandledDispatchAction.LogAndDrop,
+                    publish: framework_1.ZLinkUnhandledDispatchAction.LogAndDrop
+                },
+                diagnostics: {
+                    messageFlow: 'errors',
+                    sampleRate: 1,
+                    includeMessageSizes: false
+                }
+            }
+        };
+        return framework_loader_1.framework.createIntegrationDispatchOptionsBuilder(this.state.additionalOptions.dispatch);
+    }
+    configureInboundDispatch() {
+        const options = { ...this.state.additionalOptions };
+        this.state.additionalOptions = options;
+        return framework_loader_1.framework.createIntegrationInboundDispatchOptionsBuilder(options);
+    }
+    addLocationStore(store) {
+        this.state.additionalOptions = {
+            ...this.state.additionalOptions,
+            locations: {
+                ...(this.state.additionalOptions.locations ?? {}),
+                storeInstance: store
+            }
+        };
+        return this;
+    }
+    addRelocationStore(store) {
+        this.state.additionalOptions = {
+            ...this.state.additionalOptions,
+            locations: {
+                ...(this.state.additionalOptions.locations ?? {}),
+                relocationStoreInstance: store
+            }
+        };
+        return this;
+    }
+    setApplicationVersion(version) {
+        this.state.additionalOptions = {
+            ...this.state.additionalOptions,
+            applicationVersion: version
+        };
+        return this;
+    }
+    setMaintenanceWave(waveId) {
+        this.state.additionalOptions = {
+            ...this.state.additionalOptions,
+            maintenanceWave: waveId
+        };
+        return this;
+    }
+    setActorTransferTimeout(timeoutMs) {
+        this.state.additionalOptions = {
+            ...this.state.additionalOptions,
+            actorTransferTimeoutMs: framework_loader_1.framework.validateActorTransferTimeout(timeoutMs)
+        };
+        return this;
+    }
+    setMessageFollowDuration(timeoutMs) {
+        this.state.additionalOptions = {
+            ...this.state.additionalOptions,
+            messageFollowDurationMs: framework_loader_1.framework.validateMessageFollowDuration(timeoutMs)
+        };
+        return this;
+    }
+    setSessionReplacementCallbackTimeout(timeoutMs) {
+        this.state.additionalOptions = {
+            ...this.state.additionalOptions,
+            sessionReplacementCallbackTimeoutMs: framework_loader_1.framework.validateSessionReplacementCallbackTimeout(timeoutMs)
+        };
+        return this;
+    }
+    configureStreamCompression() {
+        const compression = { ...(this.state.additionalOptions.streamCompression ?? {}) };
+        this.state.additionalOptions = { ...this.state.additionalOptions, streamCompression: compression };
+        return framework_loader_1.framework.createIntegrationStreamCompressionBuilder(compression);
+    }
+    configureLocations() {
+        this.state.additionalOptions = {
+            ...this.state.additionalOptions,
+            locations: this.state.additionalOptions.locations ?? { options: {} }
+        };
+        const locations = this.state.additionalOptions.locations;
+        locations.options ??= {};
+        return framework_loader_1.framework.createIntegrationLocationOptionsBuilder(locations.options);
+    }
+    configureNetwork() {
+        const network = {
+            bindHost: '127.0.0.1',
+            ...(this.state.additionalOptions.network ?? {})
+        };
+        this.state.additionalOptions = {
+            ...this.state.additionalOptions,
+            network
+        };
+        return network;
+    }
+    addFanoutChannel(name) {
+        ensureChannelAvailable(this.state, name);
+        this.state.fanoutChannels[name] = {};
+        return new DefaultZLinkNestFanoutChannelBuilder(this.state, name, this.state.fanoutChannels[name]);
+    }
+    addClientServerChannel(name) {
+        ensureClientServerChannelAvailable(this.state, name);
+        this.state.clientServerChannels[name] ??= {};
+        return new DefaultZLinkNestClientServerChannelRoleBuilder(this.state, name, this.state.clientServerChannels[name]);
+    }
+    addRouteMesh(name) {
+        if (name.trim().length === 0 || name.trim() !== name) {
+            throw new framework_loader_1.framework.ZLinkConfigurationException('RouteMesh name must not be empty or padded.');
+        }
+        if (Object.prototype.hasOwnProperty.call(this.state.spotNodes, name)) {
+            throw new framework_loader_1.framework.ZLinkConfigurationException(`Duplicate RouteMesh '${name}'.`);
+        }
+        this.state.spotNodes[name] = { router: { port: 0 } };
+        return new DefaultZLinkNestMeshNodeBuilder(this.state, name, this.state.spotNodes[name]);
+    }
+    addStreamNode(name) {
+        this.state.streams[name] ??= {};
+        return new DefaultZLinkNestStreamNodeBuilder(this.state, this.state.streams[name]);
+    }
+    build() {
+        const options = {
+            [contracts_1.ZLINK_MODULE_OPTIONS_BRAND]: true,
+            implicitHandlerAutoRegistration: this.state.implicitHandlerAutoRegistration,
+            ...this.state.additionalOptions,
+            clientServerChannels: { ...this.state.clientServerChannels },
+            fanoutChannels: { ...this.state.fanoutChannels },
+            streams: { ...this.state.streams },
+            spotNodes: { ...this.state.spotNodes },
+            codecs: this.state.codecOptions.serializers.length === 0 &&
+                this.state.codecOptions.streamCodecs.length === 0
+                ? undefined
+                : {
+                    serializers: [...this.state.codecOptions.serializers],
+                    streamCodecs: [...this.state.codecOptions.streamCodecs]
+                }
+        };
+        return options;
+    }
+}
+class DefaultZLinkNestFrameworkOptionsBuilder extends ZLinkNestOptionsBuilder {
+    constructor() {
+        super(createBuilderState());
+    }
+}
+class DefaultZLinkNestCodecRegistryBuilder extends ZLinkNestOptionsBuilder {
+    constructor(state) {
+        super(state);
+    }
+    addSerializer(contentType, serializer, canSerialize) {
+        registerSerializer(this.state, contentType, serializer, canSerialize);
+        return this;
+    }
+    addStreamCodec(contentType, codec) {
+        if (contentType.trim().length === 0) {
+            throw new Error('Codec content type must not be empty.');
+        }
+        registerStreamCodec(this.state, contentType, codec);
+        return this;
+    }
+    use(extension) {
+        extension.register(this);
+        return this;
+    }
+}
+class DefaultZLinkNestFanoutChannelBuilder extends ZLinkNestOptionsBuilder {
+    name;
+    channelOptions;
+    subscriberMode;
+    constructor(state, name, channelOptions) {
+        super(state);
+        this.name = name;
+        this.channelOptions = channelOptions;
+    }
+    enablePublisher(endpointOrPort) {
+        this.channelOptions.publisher = typeof endpointOrPort === 'string'
+            ? { bind: endpointOrPort }
+            : { port: requireListenerPort(endpointOrPort, `Fanout channel '${this.name}' publisher`) };
+        return this;
+    }
+    setBindHost(bindHost) {
+        requireClientServerText(bindHost, `Fanout channel '${this.name}' publisher bind host`);
+        this.updatePublisher({ bindHost });
+        return this;
+    }
+    setAdvertiseHost(advertiseHost) {
+        requireClientServerText(advertiseHost, `Fanout channel '${this.name}' publisher advertise host`);
+        this.updatePublisher({ advertiseHost });
+        return this;
+    }
+    routingId(routingId) {
+        rejectGeneratedRoutingId(this.channelOptions.routingIdPrefix, this.name);
+        this.channelOptions.routingId = routingId;
+        return this;
+    }
+    setRoutingIdPrefix(prefix) {
+        rejectFixedRoutingId(this.channelOptions.routingId, this.name);
+        this.channelOptions.routingIdPrefix = framework_loader_1.framework.validateRoutingIdPrefix(prefix);
+        return this;
+    }
+    enableSubscriber(endpoint) {
+        const mode = endpoint === undefined ? 'automatic' : 'manual';
+        if (this.subscriberMode !== undefined && this.subscriberMode !== mode) {
+            throw new framework_loader_1.framework.ZLinkConfigurationException(`Fanout channel '${this.name}' cannot combine automatic and manual subscriber sources.`);
+        }
+        this.subscriberMode = mode;
+        this.channelOptions.subscriber = endpoint === undefined ? {} : { manualConnections: endpointList(endpoint) };
+        return this;
+    }
+    addHandlerGroup(groupName) {
+        this.channelOptions.handlerGroups = [...(this.channelOptions.handlerGroups ?? []), groupName];
+        return this;
+    }
+    addPublishHandler(packetName, handlerType) {
+        this.channelOptions.publishHandlerTypes = [...(this.channelOptions.publishHandlerTypes ?? []), { packetName, handlerType }];
+        return this;
+    }
+    updatePublisher(values) {
+        if (this.channelOptions.publisher === undefined) {
+            throw new framework_loader_1.framework.ZLinkConfigurationException(`Fanout channel '${this.name}' publisher must be enabled before configuring its listener.`);
+        }
+        this.channelOptions.publisher = { ...this.channelOptions.publisher, ...values };
+    }
+}
+class DefaultZLinkNestClientServerChannelRoleBuilder extends ZLinkNestOptionsBuilder {
+    name;
+    channel;
+    constructor(state, name, channel) {
+        super(state);
+        this.name = name;
+        this.channel = channel;
+    }
+    client() {
+        if (this.channel.client !== undefined) {
+            throw this.duplicate('Client');
+        }
+        this.channel.client = { manualConnections: [] };
+        return new DefaultZLinkNestClientServerChannelClientBuilder(this.state, this.name, this.channel);
+    }
+    server() {
+        if (this.channel.server !== undefined) {
+            throw this.duplicate('Server');
+        }
+        this.channel.server = {};
+        return new DefaultZLinkNestClientServerChannelServerBuilder(this.state, this.name, this.channel);
+    }
+    duplicate(role) {
+        return new framework_loader_1.framework.ZLinkConfigurationException(`ClientServer channel '${this.name}' ${role} role is already registered.`);
+    }
+}
+class DefaultZLinkNestClientServerChannelClientBuilder extends ZLinkNestOptionsBuilder {
+    name;
+    channel;
+    constructor(state, name, channel) {
+        super(state);
+        this.name = name;
+        this.channel = channel;
+    }
+    connect(endpoint) {
+        requireClientServerText(endpoint, `ClientServer channel '${this.name}' endpoint`);
+        const connections = [...(this.channel.client?.manualConnections ?? [])];
+        if (!connections.includes(endpoint))
+            connections.push(endpoint);
+        this.channel.client = { ...this.channel.client, manualConnections: connections };
+        return this;
+    }
+}
+class DefaultZLinkNestClientServerChannelServerBuilder extends ZLinkNestOptionsBuilder {
+    name;
+    channel;
+    constructor(state, name, channel) {
+        super(state);
+        this.name = name;
+        this.channel = channel;
+    }
+    listen(port = 0) {
+        if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+            throw new framework_loader_1.framework.ZLinkConfigurationException(`ClientServer channel '${this.name}' port must be between 0 and 65535.`);
+        }
+        this.updateServer({ port });
+        this.updateBind();
+        return this;
+    }
+    setBindHost(bindHost) {
+        requireClientServerText(bindHost, `ClientServer channel '${this.name}' bind host`);
+        this.updateServer({ bindHost });
+        if (this.server.port !== undefined)
+            this.updateBind();
+        return this;
+    }
+    setAdvertiseHost(advertiseHost) {
+        requireClientServerText(advertiseHost, `ClientServer channel '${this.name}' advertise host`);
+        this.updateServer({ advertiseHost });
+        return this;
+    }
+    setWeight(weight) {
+        if (!Number.isInteger(weight) || weight < 0 || weight > 10_000) {
+            throw new framework_loader_1.framework.ZLinkConfigurationException(`ClientServer channel '${this.name}' weight must be between 0 and 10000.`);
+        }
+        this.updateServer({ weight });
+        return this;
+    }
+    addSendHandler(packetName, handlerType) {
+        requireClientServerText(packetName, `ClientServer channel '${this.name}' send packet name`);
+        this.channel.sendHandlerTypes = [
+            ...(this.channel.sendHandlerTypes ?? []),
+            { packetName, handlerType }
+        ];
+        return this;
+    }
+    addRequestHandler(packetName, handlerType) {
+        requireClientServerText(packetName, `ClientServer channel '${this.name}' request packet name`);
+        this.channel.requestHandlerTypes = [
+            ...(this.channel.requestHandlerTypes ?? []),
+            { packetName, handlerType }
+        ];
+        return this;
+    }
+    addHandlerGroup(groupName) {
+        requireClientServerText(groupName, `ClientServer channel '${this.name}' handler group`);
+        this.channel.handlerGroups = [...(this.channel.handlerGroups ?? []), groupName];
+        return this;
+    }
+    get server() {
+        return this.channel.server;
+    }
+    updateServer(values) {
+        this.channel.server = { ...this.channel.server, ...values };
+    }
+    updateBind() {
+        const host = this.server.bindHost ?? '127.0.0.1';
+        const endpointHost = host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+        this.updateServer({ bind: `tcp://${endpointHost}:${this.server.port ?? 0}` });
+    }
+}
+function requireClientServerText(value, label) {
+    if (value.trim().length === 0 || value.trim() !== value) {
+        throw new framework_loader_1.framework.ZLinkConfigurationException(`${label} must not be empty or padded.`);
+    }
+}
+function requireListenerPort(port, label) {
+    const normalized = port ?? 0;
+    if (!Number.isInteger(normalized) || normalized < 0 || normalized > 65_535) {
+        throw new framework_loader_1.framework.ZLinkConfigurationException(`${label} port must be between 0 and 65535.`);
+    }
+    return normalized;
+}
+function requirePublicWeight(value, label) {
+    if (!Number.isInteger(value) || value < 0 || value > 10_000) {
+        throw new framework_loader_1.framework.ZLinkConfigurationException(`${label} must be an integer in 0..10000.`);
+    }
+    return value;
+}
+function rejectFixedRoutingId(routingId, memberName) {
+    if (routingId !== undefined) {
+        throw new framework_loader_1.framework.ZLinkConfigurationException(`Mesh member '${memberName}' cannot combine a fixed routing id with a generated prefix.`);
+    }
+}
+function rejectGeneratedRoutingId(prefix, memberName) {
+    if (prefix !== undefined) {
+        throw new framework_loader_1.framework.ZLinkConfigurationException(`Mesh member '${memberName}' cannot combine a generated routing-id prefix with a fixed id.`);
+    }
+}
+class DefaultZLinkNestStreamNodeBuilder extends ZLinkNestOptionsBuilder {
+    streamOptions;
+    constructor(state, streamOptions) {
+        super(state);
+        this.streamOptions = streamOptions;
+    }
+    bind(endpointOrPort) {
+        if (typeof endpointOrPort === 'string') {
+            this.streamOptions.bind = endpointOrPort;
+            delete this.streamOptions.port;
+        }
+        else {
+            this.streamOptions.port = requireListenerPort(endpointOrPort, 'STREAM listener');
+            delete this.streamOptions.bind;
+        }
+        return this;
+    }
+    setBindHost(bindHost) {
+        requireClientServerText(bindHost, 'STREAM bind host');
+        this.streamOptions.bindHost = bindHost;
+        return this;
+    }
+    setAdvertiseHost(advertiseHost) {
+        requireClientServerText(advertiseHost, 'STREAM advertise host');
+        this.streamOptions.advertiseHost = advertiseHost;
+        return this;
+    }
+    enableActorDispatch() {
+        if (this.streamOptions.actorDispatchEnabled === true) {
+            throw new framework_loader_1.framework.ZLinkConfigurationException('STREAM node actor dispatch is already enabled.');
+        }
+        this.streamOptions.actorDispatchEnabled = true;
+        return this;
+    }
+    setTlsServer(certificatePath, keyPath, requireClientCertificate = false) {
+        this.streamOptions.tlsServer = {
+            certificatePath,
+            keyPath,
+            requireClientCertificate
+        };
+        return this;
+    }
+    registerSession(sessionType) {
+        if (this.streamOptions.session !== undefined) {
+            throw new framework_loader_1.framework.ZLinkConfigurationException('STREAM node cannot register more than one header stream session.');
+        }
+        this.streamOptions.session = sessionType;
+        return this;
+    }
+}
+class DefaultZLinkNestMeshNodeBuilder extends ZLinkNestOptionsBuilder {
+    name;
+    spotOptions;
+    constructor(state, name, spotOptions) {
+        super(state);
+        this.name = name;
+        this.spotOptions = spotOptions;
+    }
+    channel(name) {
+        if (name.trim().length === 0 || name.trim() !== name) {
+            throw new framework_loader_1.framework.ZLinkConfigurationException('Mesh channel name must not be empty or padded.');
+        }
+        const channels = {
+            ...(this.spotOptions.meshChannels ?? {})
+        };
+        if (Object.prototype.hasOwnProperty.call(channels, name)) {
+            throw new framework_loader_1.framework.ZLinkConfigurationException(`Duplicate channel '${name}' in RouteMesh '${this.name}'.`);
+        }
+        channels[name] = {};
+        this.spotOptions.meshChannels = channels;
+        return new DefaultZLinkNestMeshChannelBuilder(this.state, channels[name]);
+    }
+    listen(endpointOrPort) {
+        this.spotOptions.router = typeof endpointOrPort === 'string'
+            ? { ...(this.spotOptions.router ?? {}), bind: endpointOrPort, port: undefined }
+            : {
+                ...(this.spotOptions.router ?? {}),
+                bind: undefined,
+                port: requireListenerPort(endpointOrPort, `RouteMesh '${this.name}' listener`)
+            };
+        return this;
+    }
+    setBindHost(bindHost) {
+        requireClientServerText(bindHost, `RouteMesh '${this.name}' bind host`);
+        this.spotOptions.router = { ...(this.spotOptions.router ?? {}), bindHost };
+        return this;
+    }
+    setAdvertiseHost(advertiseHost) {
+        requireClientServerText(advertiseHost, `RouteMesh '${this.name}' advertise host`);
+        this.spotOptions.router = { ...(this.spotOptions.router ?? {}), advertiseHost };
+        return this;
+    }
+    routingId(routingId) {
+        rejectGeneratedRoutingId(this.spotOptions.routingIdPrefix, this.name);
+        this.spotOptions.routingId = routingId;
+        if (this.spotOptions.router !== undefined) {
+            this.spotOptions.router.routingId = routingId;
+        }
+        if (this.spotOptions.pubSub !== undefined) {
+            this.spotOptions.pubSub.routingId = routingId;
+        }
+        return this;
+    }
+    setRoutingIdPrefix(prefix) {
+        rejectFixedRoutingId(this.spotOptions.routingId, this.name);
+        this.spotOptions.routingIdPrefix = framework_loader_1.framework.validateRoutingIdPrefix(prefix);
+        return this;
+    }
+    setPlacementWeight(weight) {
+        if (!Number.isInteger(weight) || weight < 0 || weight > 10_000) {
+            throw new framework_loader_1.framework.ZLinkConfigurationException('Placement weight must be an integer in 0..10000.');
+        }
+        this.spotOptions.placementWeight = weight;
+        return this;
+    }
+    setActorLimit(limit) {
+        this.spotOptions.actorLimit = requireCapacity(limit, 'Actor limit');
+        return this;
+    }
+    setSpotLimit(limit) {
+        this.spotOptions.spotLimit = requireCapacity(limit, 'Spot limit');
+        return this;
+    }
+    setActivationConcurrency(limit) {
+        this.spotOptions.activationConcurrencyLimit = requirePositiveCapacity(limit, 'Activation concurrency limit');
+        return this;
+    }
+    setInstanceSpotIdleTimeout(timeoutMs) {
+        this.spotOptions.instanceSpotIdleTimeoutMs = requireNonNegativeSafeInteger(timeoutMs, 'Instance Spot idle timeout');
+        return this;
+    }
+    configureRouterSocket() {
+        this.spotOptions.router ??= {};
+        return this.spotOptions.router;
+    }
+    configureSpotPublisher() {
+        this.spotOptions.publisherConfig ??= {};
+        return this.spotOptions.publisherConfig;
+    }
+    peerConnections() {
+        this.spotOptions.router ??= {};
+        return new DefaultZLinkNestMeshPeerConnections(this.spotOptions.router);
+    }
+    objects() {
+        return new DefaultZLinkNestMeshObjectRoleBuilder(this.state, this.name, this.spotOptions);
+    }
+    addSendHandler(packetName, handlerType) {
+        this.spotOptions.routeSendHandlers = [
+            ...(this.spotOptions.routeSendHandlers ?? []),
+            { packetName, handlerType }
+        ];
+        return this;
+    }
+    addRequestHandler(packetName, handlerType) {
+        this.spotOptions.routeRequestHandlers = [
+            ...(this.spotOptions.routeRequestHandlers ?? []),
+            { packetName, handlerType }
+        ];
+        return this;
+    }
+}
+class DefaultZLinkNestMeshObjectRoleBuilder extends ZLinkNestOptionsBuilder {
+    meshName;
+    node;
+    constructor(state, meshName, node) {
+        super(state);
+        this.meshName = meshName;
+        this.node = node;
+    }
+    client() {
+        this.node.objectRole = 'client';
+        return new DefaultZLinkNestMeshObjectClientBuilder(this.state);
+    }
+    server() {
+        this.node.objectRole = 'server';
+        return new DefaultZLinkNestMeshObjectServerBuilder(this.state, this.meshName, this.node);
+    }
+}
+class DefaultZLinkNestMeshObjectClientBuilder extends ZLinkNestOptionsBuilder {
+}
+class DefaultZLinkNestFactoryBuilder {
+    relocation;
+    sealed = false;
+    disable() {
+        this.select({ kind: 'disabled' });
+    }
+    recreate() {
+        this.select({ kind: 'recreate' });
+    }
+    preserve(adapterType) {
+        if (typeof adapterType !== 'function') {
+            throw new framework_loader_1.framework.ZLinkConfigurationException('PreserveStateWith relocation requires an adapter type.');
+        }
+        this.select({ kind: 'snapshot', adapterType });
+    }
+    relocationConfiguration() {
+        if (this.relocation === undefined) {
+            throw new framework_loader_1.framework.ZLinkConfigurationException('Factory configure callback must select exactly one relocation policy.');
+        }
+        return this.relocation;
+    }
+    seal() {
+        this.sealed = true;
+    }
+    assertMutable() {
+        if (this.sealed) {
+            throw new framework_loader_1.framework.ZLinkConfigurationException('Factory builder cannot be changed after the configure callback returns.');
+        }
+    }
+    select(relocation) {
+        this.assertMutable();
+        if (this.relocation !== undefined) {
+            throw new framework_loader_1.framework.ZLinkConfigurationException('Factory configure callback must select exactly one relocation policy.');
+        }
+        this.relocation = relocation;
+    }
+}
+class DefaultZLinkNestActorFactoryBuilder extends DefaultZLinkNestFactoryBuilder {
+    disableRelocation() {
+        this.disable();
+    }
+    recreateOnRelocation() {
+        this.recreate();
+    }
+    preserveStateWith(adapterType) {
+        this.preserve(adapterType);
+    }
+    build() {
+        return { options: {}, relocation: this.relocationConfiguration() };
+    }
+}
+class DefaultZLinkNestUserSpotFactoryBuilder extends DefaultZLinkNestFactoryBuilder {
+    stableTypeLimitValue;
+    executionModeValue = framework_1.ZLinkUserSpotExecutionMode.SpotWide;
+    relocationCoordinationModeValue = framework_1.ZLinkSpotRelocationCoordinationMode.FrameworkManaged;
+    stableTypeLimit(limit) {
+        this.assertMutable();
+        validateStableTypeLimit(limit);
+        this.stableTypeLimitValue = limit;
+        return this;
+    }
+    executionMode(mode) {
+        this.assertMutable();
+        this.executionModeValue = mode;
+        return this;
+    }
+    relocationCoordinationMode(mode) {
+        this.assertMutable();
+        this.relocationCoordinationModeValue = mode;
+        return this;
+    }
+    disableRelocation() {
+        this.disable();
+    }
+    recreateOnRelocation() {
+        this.recreate();
+    }
+    preserveStateWith(adapterType) {
+        this.preserve(adapterType);
+    }
+    build() {
+        const relocation = this.relocationConfiguration();
+        const options = {
+            stableTypeLimit: this.stableTypeLimitValue,
+            executionMode: this.executionModeValue,
+            relocationCoordinationMode: this.relocationCoordinationModeValue
+        };
+        validateUserSpotFactoryConfiguration(options);
+        if (options.executionMode === framework_1.ZLinkUserSpotExecutionMode.PerActor
+            && relocation.kind !== 'recreate') {
+            throw new framework_loader_1.framework.ZLinkConfigurationException('PerActor User Spots require RecreateOnRelocation.');
+        }
+        return { options, relocation };
+    }
+}
+class DefaultZLinkNestInstanceSpotFactoryBuilder extends DefaultZLinkNestFactoryBuilder {
+    stableTypeLimitValue;
+    stableTypeLimit(limit) {
+        this.assertMutable();
+        validateStableTypeLimit(limit);
+        this.stableTypeLimitValue = limit;
+        return this;
+    }
+    disableRelocation() {
+        this.disable();
+    }
+    recreateOnRelocation() {
+        this.recreate();
+    }
+    preserveStateWith(adapterType) {
+        this.preserve(adapterType);
+    }
+    build() {
+        return {
+            options: { stableTypeLimit: this.stableTypeLimitValue },
+            relocation: this.relocationConfiguration()
+        };
+    }
+}
+class DefaultZLinkNestMeshObjectServerBuilder extends ZLinkNestOptionsBuilder {
+    meshName;
+    node;
+    constructor(state, meshName, node) {
+        super(state);
+        this.meshName = meshName;
+        this.node = node;
+    }
+    addEntrySpot(entrySpotType) {
+        framework_loader_1.framework.registerEntrySpot(this.node, entrySpotType);
+        return this;
+    }
+    addSpotFactory(spotType, implementation, configure) {
+        const stableType = validateObjectFactory(spotType, 'User Spot type');
+        requireFactoryConfigure(configure);
+        const factory = new DefaultZLinkNestUserSpotFactoryBuilder();
+        let built;
+        try {
+            configure(factory);
+            built = factory.build();
+        }
+        finally {
+            factory.seal();
+        }
+        const { options, relocation } = built;
+        const registrations = {
+            ...(this.node.spotFactoryRegistrations ?? {})
+        };
+        rejectDuplicateObjectType(registrations, stableType, this.meshName);
+        registrations[stableType] = {
+            implementation,
+            options: {
+                ...options,
+                executionMode: options.executionMode
+            },
+            relocation
+        };
+        this.node.spotFactoryRegistrations = registrations;
+        const factories = [...(this.node.spotFactories ?? [])];
+        framework_loader_1.framework.registerSpotFactory({ spotFactories: factories }, implementation);
+        this.node.spotFactories = factories;
+        return this;
+    }
+    addInstanceSpotFactory(instanceSpotType, implementation, configure) {
+        const stableType = validateObjectFactory(instanceSpotType, 'Instance Spot type');
+        requireFactoryConfigure(configure);
+        const factory = new DefaultZLinkNestInstanceSpotFactoryBuilder();
+        let built;
+        try {
+            configure(factory);
+            built = factory.build();
+        }
+        finally {
+            factory.seal();
+        }
+        const { options, relocation } = built;
+        validateStableTypeLimit(options.stableTypeLimit);
+        const factories = {
+            ...(this.node.instanceSpotFactories ?? {})
+        };
+        if (Object.hasOwn(factories, stableType)) {
+            throw new framework_loader_1.framework.ZLinkConfigurationException(`Duplicate Instance Spot factory '${stableType}' on RouteMesh '${this.meshName}'.`);
+        }
+        factories[stableType] = implementation;
+        this.node.instanceSpotFactories = factories;
+        this.node.instanceSpotFactoryRegistrations = {
+            ...(this.node.instanceSpotFactoryRegistrations ?? {}),
+            [stableType]: { implementation, options, relocation }
+        };
+        return this;
+    }
+    addActorFactory(actorType, implementation, configure) {
+        const stableType = validateObjectFactory(actorType, 'Actor type');
+        requireFactoryConfigure(configure);
+        const factory = new DefaultZLinkNestActorFactoryBuilder();
+        let built;
+        try {
+            configure(factory);
+            built = factory.build();
+        }
+        finally {
+            factory.seal();
+        }
+        const { options, relocation } = built;
+        const registrations = {
+            ...(this.node.actorFactoryRegistrations ?? {})
+        };
+        rejectDuplicateObjectType(registrations, stableType, this.meshName);
+        const actorFactories = {
+            ...this.node.actorFactories
+        };
+        framework_loader_1.framework.registerActorFactory({ actorFactories }, stableType, implementation);
+        this.node.actorFactories = actorFactories;
+        registrations[stableType] = { implementation, options, relocation };
+        this.node.actorFactoryRegistrations = registrations;
+        return this;
+    }
+}
+function validateObjectFactory(stableType, label) {
+    if (typeof stableType !== 'string'
+        || Buffer.byteLength(stableType) < 1
+        || Buffer.byteLength(stableType) > 255
+        || stableType.includes('\0')) {
+        throw new framework_loader_1.framework.ZLinkConfigurationException(`${label} must contain 1..255 UTF-8 bytes and no NUL.`);
+    }
+    return stableType;
+}
+function requireFactoryConfigure(configure) {
+    if (typeof configure !== 'function') {
+        throw new framework_loader_1.framework.ZLinkConfigurationException('Object factory requires a configure callback.');
+    }
+}
+function validateUserSpotFactoryConfiguration(options) {
+    validateStableTypeLimit(options.stableTypeLimit);
+    const executionMode = options.executionMode;
+    const relocationCoordinationMode = options.relocationCoordinationMode;
+    if (executionMode !== framework_1.ZLinkUserSpotExecutionMode.SpotWide
+        && executionMode !== framework_1.ZLinkUserSpotExecutionMode.PerActor) {
+        throw new framework_loader_1.framework.ZLinkConfigurationException('User Spot executionMode is invalid.');
+    }
+    if (relocationCoordinationMode !== framework_1.ZLinkSpotRelocationCoordinationMode.FrameworkManaged
+        && relocationCoordinationMode !== framework_1.ZLinkSpotRelocationCoordinationMode.ApplicationSignaled) {
+        throw new framework_loader_1.framework.ZLinkConfigurationException('User Spot relocationCoordinationMode is invalid.');
+    }
+    if (options.executionMode === framework_1.ZLinkUserSpotExecutionMode.PerActor
+        && options.relocationCoordinationMode === framework_1.ZLinkSpotRelocationCoordinationMode.ApplicationSignaled) {
+        throw new framework_loader_1.framework.ZLinkConfigurationException('ApplicationSignaled relocation coordination mode is valid only for SpotWide User Spots.');
+    }
+}
+function validateStableTypeLimit(value) {
+    if (value !== undefined
+        && (!Number.isInteger(value) || value < 0 || value > 2_147_483_647)) {
+        throw new framework_loader_1.framework.ZLinkConfigurationException('stableTypeLimit must be an integer from 0 through 2147483647.');
+    }
+}
+function requirePositiveCapacity(value, label) {
+    if (!Number.isSafeInteger(value) || value <= 0 || value > 0x7fff_ffff) {
+        throw new framework_loader_1.framework.ZLinkConfigurationException(`${label} must be an integer in 1..2147483647.`);
+    }
+    return value;
+}
+function requireCapacity(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0 || value > 0x7fff_ffff) {
+        throw new framework_loader_1.framework.ZLinkConfigurationException(`${label} must be an integer in 0..2147483647.`);
+    }
+    return value;
+}
+function requireNonNegativeSafeInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new framework_loader_1.framework.ZLinkConfigurationException(`${label} must be a non-negative safe integer.`);
+    }
+    return value;
+}
+function rejectDuplicateObjectType(registrations, stableType, meshName) {
+    if (Object.hasOwn(registrations, stableType)) {
+        throw new framework_loader_1.framework.ZLinkConfigurationException(`Duplicate object factory '${stableType}' on RouteMesh '${meshName}'.`);
+    }
+}
+class DefaultZLinkNestMeshChannelBuilder extends ZLinkNestOptionsBuilder {
+    channel;
+    constructor(state, channel) {
+        super(state);
+        this.channel = channel;
+    }
+    client() {
+        if (this.channel.client === true || this.channel.server === true) {
+            throw new framework_loader_1.framework.ZLinkConfigurationException('RouteMesh channel must register exactly one role; client() and server() cannot both be used or called twice.');
+        }
+        this.channel.client = true;
+        return new DefaultZLinkNestMeshChannelClientBuilder(this.state);
+    }
+    server() {
+        if (this.channel.client === true || this.channel.server === true) {
+            throw new framework_loader_1.framework.ZLinkConfigurationException('RouteMesh channel must register exactly one role; client() and server() cannot both be used or called twice.');
+        }
+        this.channel.server = true;
+        return new DefaultZLinkNestMeshChannelServerBuilder(this.state, this.channel);
+    }
+}
+class DefaultZLinkNestMeshChannelClientBuilder extends ZLinkNestOptionsBuilder {
+}
+class DefaultZLinkNestMeshChannelServerBuilder extends ZLinkNestOptionsBuilder {
+    channel;
+    constructor(state, channel) {
+        super(state);
+        this.channel = channel;
+    }
+    setWeight(weight) {
+        this.channel.weight = requirePublicWeight(weight, 'Mesh channel weight');
+        return this;
+    }
+    addSendHandler(packetName, handlerType) {
+        this.channel.sendHandlers = [...(this.channel.sendHandlers ?? []), { packetName, handlerType }];
+        return this;
+    }
+    addRequestHandler(packetName, handlerType) {
+        this.channel.requestHandlers = [...(this.channel.requestHandlers ?? []), { packetName, handlerType }];
+        return this;
+    }
+    addHandlerGroup(groupName) {
+        this.channel.handlerGroups = [...(this.channel.handlerGroups ?? []), groupName];
+        return this;
+    }
+}
+class DefaultZLinkNestMeshPeerConnections {
+    router;
+    constructor(router) {
+        this.router = router;
+    }
+    connect(expectedRoutingIdOrEndpoint, endpoint) {
+        if (endpoint === undefined) {
+            this.router.manualConnections = [...(this.router.manualConnections ?? []), expectedRoutingIdOrEndpoint];
+            return;
+        }
+        this.router.manualPeerConnections = [
+            ...(this.router.manualPeerConnections ?? []),
+            { peerRid: expectedRoutingIdOrEndpoint, endpoint }
+        ];
+    }
+    disconnect(endpoint) {
+        this.router.manualConnections = (this.router.manualConnections ?? [])
+            .filter((value) => value !== endpoint);
+        this.router.manualPeerConnections = (this.router.manualPeerConnections ?? [])
+            .filter((value) => value.endpoint !== endpoint);
+    }
+    listConnections() {
+        return [
+            ...(this.router.manualConnections ?? []).map((endpoint) => ({ endpoint })),
+            ...(this.router.manualPeerConnections ?? []).map((connection) => ({
+                endpoint: connection.endpoint,
+                expectedRoutingId: connection.peerRid
+            }))
+        ];
+    }
+}
+function endpointList(endpoint) {
+    return typeof endpoint === 'string' ? [endpoint] : [...endpoint];
+}
+function createZLinkNestFrameworkOptionsBuilder() {
+    return new DefaultZLinkNestFrameworkOptionsBuilder();
+}