@zlink-systems/framework 0.10.0

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

@@ -0,0 +1,153 @@
+import type { ZLinkActor, ZLinkActorFactory } from '../Actors';
+import type { ZLinkEntrySpot, ZLinkInstanceSpot, ZLinkSpot } from '../Spots';
+import type { ZLinkSession, ZLinkSessionFactory, ZLinkStreamCompressionCodec } from '../Streams';
+import type { ZLinkEndpointConnections } from './Connections';
+import type { ZLinkCodecRegistryBuilder } from '../Codecs';
+import type { ZLinkDispatchOptionsBuilder, ZLinkInboundDispatchOptions } from '../Dispatch';
+import type { ZLinkLocationOptions, ZLinkLocationStore, ZLinkRelocationStore } from '../Locations';
+import type { RoutingId, Type } from '../Common';
+import type { ZLinkWorkerOptions } from './RegistrationTypes';
+import type { ZLinkSpotPublisherConfig } from './Configs';
+import type { ZLinkActorFactoryBuilder, ZLinkInstanceSpotFactoryBuilder, ZLinkUserSpotFactoryBuilder } from './ObjectRoles';
+import type { ZLinkRequestHandler, ZLinkRouteRequestHandler, ZLinkRouteSendHandler, ZLinkSendHandler } from '../Handlers';
+export interface ZLinkFrameworkOptions {
+    codecs(): ZLinkCodecRegistryBuilder;
+    configureNetwork(): ZLinkNetworkOptions;
+    /**
+     * Configures the bounded worker-thread pool used by `runCpuWorker(...)`.
+     * I/O workers do not consume these threads.
+     */
+    configureWorker(options: ZLinkWorkerOptions): this;
+    configureDispatch(): ZLinkDispatchOptionsBuilder;
+    configureInboundDispatch(): ZLinkInboundDispatchOptions;
+    addLocationStore(store: ZLinkLocationStore): this;
+    addRelocationStore(store: ZLinkRelocationStore): this;
+    setApplicationVersion(version: bigint): this;
+    setMaintenanceWave(waveId: string): this;
+    setActorTransferTimeout(timeoutMs: number): this;
+    /** Sets how long Message Follow relays traffic from the previous owner. */
+    setMessageFollowDuration(timeoutMs: number): this;
+    /** Sets the maximum duration for a replaced Session callback before its connection is closed. */
+    setSessionReplacementCallbackTimeout(timeoutMs: number): this;
+    configureLocations(): ZLinkLocationOptions;
+    configureStreamCompression(): ZLinkStreamCompressionBuilder;
+    addRouteMesh(meshName: string): ZLinkMeshNodeBuilder;
+    addClientServerChannel(name: string): ZLinkClientServerChannelRoleBuilder;
+    addFanoutChannel(name: string): ZLinkFanoutChannelBuilder;
+    addStreamNode(name: string): ZLinkStreamNodeBuilder;
+}
+export interface ZLinkClientServerChannelRoleBuilder {
+    client(): ZLinkClientServerChannelClientBuilder;
+    server(): ZLinkClientServerChannelServerBuilder;
+}
+export interface ZLinkClientServerChannelClientBuilder {
+    connect(endpoint: string): this;
+}
+export interface ZLinkClientServerChannelServerBuilder {
+    listen(port?: number): this;
+    setBindHost(bindHost: string): this;
+    setAdvertiseHost(advertiseHost: string): this;
+    setWeight(weight: number): this;
+    addHandlerGroup(groupName: string): this;
+    addSendHandler<TMessage>(handlerType: Type<ZLinkSendHandler<TMessage>>): this;
+    addRequestHandler<TRequest, TReply>(handlerType: Type<ZLinkRequestHandler<TRequest, TReply>>): this;
+}
+export interface ZLinkMeshPeerConnection {
+    readonly endpoint: string;
+    readonly expectedRoutingId?: RoutingId;
+}
+export interface ZLinkMeshPeerConnections {
+    connect(endpoint: string): void;
+    connect(expectedRoutingId: RoutingId, endpoint: string): void;
+    disconnect(endpoint: string): void;
+    listConnections(): readonly ZLinkMeshPeerConnection[];
+}
+export interface ZLinkMeshChannelBuilder {
+    client(): ZLinkMeshChannelClientBuilder;
+    server(): ZLinkMeshChannelServerBuilder;
+}
+export interface ZLinkMeshChannelClientBuilder {
+}
+export interface ZLinkMeshChannelServerBuilder {
+    setWeight(weight: number): this;
+    addHandlerGroup(groupName: string): this;
+    addSendHandler<TMessage>(handlerType: Type<ZLinkSendHandler<TMessage>>): this;
+    addRequestHandler<TRequest, TReply>(handlerType: Type<ZLinkRequestHandler<TRequest, TReply>>): this;
+}
+export interface ZLinkMeshNodeSocketConfig {
+    sendHighWaterMark: number;
+    receiveHighWaterMark: number;
+    mailboxMessageBudget: number;
+    mailboxByteBudget: number;
+    receiveTimeoutMs?: number;
+    sendTimeoutMs?: number;
+}
+export interface ZLinkStreamSocketConfig {
+    maxMessageSize: number;
+}
+export interface ZLinkMeshNodeBuilder {
+    channel(channelName: string): ZLinkMeshChannelBuilder;
+    listen(endpoint: string): this;
+    listen(port?: number): this;
+    setBindHost(bindHost: string): this;
+    setAdvertiseHost(advertiseHost: string): this;
+    routingId(routingId: RoutingId): this;
+    setRoutingIdPrefix(prefix: string): this;
+    setPlacementWeight(weight: number): this;
+    setActorLimit(limit: number): this;
+    setSpotLimit(limit: number): this;
+    setActivationConcurrency(limit: number): this;
+    setInstanceSpotIdleTimeout(timeoutMs: number): this;
+    configureRouterSocket(): ZLinkMeshNodeSocketConfig;
+    configureSpotPublisher(): ZLinkSpotPublisherConfig;
+    peerConnections(): ZLinkMeshPeerConnections;
+    setDefaultRequestTimeout(timeoutMs: number): this;
+    objects(): ZLinkMeshObjectRoleBuilder;
+    addRouteSendHandler<TMessage>(handlerType: Type<ZLinkRouteSendHandler<TMessage>>): this;
+    addRouteRequestHandler<TRequest, TReply>(handlerType: Type<ZLinkRouteRequestHandler<TRequest, TReply>>): this;
+}
+export interface ZLinkNetworkOptions {
+    bindHost: string;
+    advertiseHost?: string;
+}
+export interface ZLinkMeshObjectRoleBuilder {
+    client(): ZLinkMeshObjectClientBuilder;
+    server(): ZLinkMeshObjectServerBuilder;
+}
+export interface ZLinkMeshObjectClientBuilder {
+}
+export interface ZLinkMeshObjectServerBuilder {
+    addEntrySpot<TEntrySpot extends ZLinkEntrySpot>(entrySpotType: Type<TEntrySpot>): this;
+    addSpotFactory<TSpot extends ZLinkSpot>(spotType: string, implementation: Type<TSpot>, configure: (builder: ZLinkUserSpotFactoryBuilder<TSpot>) => void): this;
+    addInstanceSpotFactory<TSpot extends ZLinkInstanceSpot>(instanceSpotType: string, implementation: Type<TSpot>, configure: (builder: ZLinkInstanceSpotFactoryBuilder<TSpot>) => void): this;
+    addActorFactory<TActor extends ZLinkActor>(actorType: string, implementation: Type<ZLinkActorFactory<TActor>>, configure: (builder: ZLinkActorFactoryBuilder<TActor>) => void): this;
+}
+export interface ZLinkMetadataPolicyBuilder {
+    allowSessionToActor(key: string): this;
+    allowActorToSession(key: string): this;
+}
+export interface ZLinkStreamCompressionBuilder {
+    useDefault(): this;
+    useLz4(): this;
+    use(codec: ZLinkStreamCompressionCodec): this;
+    disable(): this;
+}
+export interface ZLinkFanoutChannelBuilder {
+    enablePublisher(endpointOrPort?: string | number): this;
+    setBindHost(bindHost: string): this;
+    setAdvertiseHost(advertiseHost: string): this;
+    routingId(routingId: string): this;
+    setRoutingIdPrefix(prefix: string): this;
+    enableSubscriber(): this;
+    connect(endpoint: string): this;
+    subscriberConnections(): ZLinkEndpointConnections;
+}
+export interface ZLinkStreamNodeBuilder {
+    bind(endpointOrPort?: string | number): this;
+    setBindHost(bindHost: string): this;
+    setAdvertiseHost(advertiseHost: string): this;
+    configureSocket(): ZLinkStreamSocketConfig;
+    enableActorDispatch(): this;
+    setTlsServer(certificatePath: string, keyPath: string, requireClientCertificate?: boolean): this;
+    registerSession<TSession extends ZLinkSession>(sessionType: Type<TSession> | Type<ZLinkSessionFactory<TSession>>): this;
+}

package/dist/contracts/Configuration/Builders.js

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

package/dist/contracts/Configuration/CodecContentType.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizeCodecContentType(contentType: string): string;
+export declare function isCanonicalCodecContentType(contentType: string): boolean;

package/dist/contracts/Configuration/CodecContentType.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeCodecContentType = normalizeCodecContentType;
+exports.isCanonicalCodecContentType = isCanonicalCodecContentType;
+const ConfigurationException_1 = require("./ConfigurationException");
+const mediaTypePunctuation = new Set([..."!#$%&'*+-.^_`|~"].map((value) => value.charCodeAt(0)));
+function normalizeCodecContentType(contentType) {
+    if (typeof contentType !== 'string') {
+        throw invalidContentType();
+    }
+    let first = 0;
+    let last = contentType.length;
+    while (first < last && isOuterWhitespace(contentType.charCodeAt(first)))
+        first += 1;
+    while (last > first && isOuterWhitespace(contentType.charCodeAt(last - 1)))
+        last -= 1;
+    const value = contentType.slice(first, last);
+    let slash = -1;
+    let normalized = '';
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code === 0x2f) {
+            if (slash !== -1 || index === 0 || index === value.length - 1) {
+                throw invalidContentType();
+            }
+            slash = index;
+            normalized += '/';
+            continue;
+        }
+        if (!isTokenCharacter(code))
+            throw invalidContentType();
+        normalized += code >= 0x41 && code <= 0x5a
+            ? String.fromCharCode(code + 0x20)
+            : value[index];
+    }
+    if (slash === -1)
+        throw invalidContentType();
+    return normalized;
+}
+function isCanonicalCodecContentType(contentType) {
+    if (typeof contentType !== 'string' || contentType.length === 0)
+        return false;
+    let slash = -1;
+    for (let index = 0; index < contentType.length; index += 1) {
+        const code = contentType.charCodeAt(index);
+        if (code === 0x2f) {
+            if (slash !== -1 || index === 0 || index === contentType.length - 1)
+                return false;
+            slash = index;
+            continue;
+        }
+        if (!isTokenCharacter(code) || (code >= 0x41 && code <= 0x5a))
+            return false;
+    }
+    return slash !== -1;
+}
+function isOuterWhitespace(code) {
+    return code === 0x20 || code === 0x09;
+}
+function isTokenCharacter(code) {
+    return (code >= 0x30 && code <= 0x39)
+        || (code >= 0x41 && code <= 0x5a)
+        || (code >= 0x61 && code <= 0x7a)
+        || mediaTypePunctuation.has(code);
+}
+function invalidContentType() {
+    return new ConfigurationException_1.ZLinkConfigurationException('Codec content type must be a parameter-free ASCII type/subtype.');
+}

package/dist/contracts/Configuration/CodecSerializerSelection.d.ts

@@ -0,0 +1,9 @@
+import type { ZLinkMessageTypeSelector } from '../Codecs';
+import type { ZLinkMessageSerializer } from '../Codecs';
+export interface ZLinkCodecSerializerSelection {
+    readonly selector: ZLinkMessageTypeSelector;
+    readonly fallback: boolean;
+}
+export declare function rememberCodecSerializerSelections(serializers: ReadonlyMap<string, ZLinkMessageSerializer>, selections: ReadonlyMap<string, ZLinkCodecSerializerSelection>): ReadonlyMap<string, ZLinkMessageSerializer>;
+export declare function codecSerializerSelectionsOf(serializers: ReadonlyMap<string, ZLinkMessageSerializer>): ReadonlyMap<string, ZLinkCodecSerializerSelection> | undefined;
+export declare const matchEveryDeclaredMessageType: ZLinkMessageTypeSelector;

package/dist/contracts/Configuration/CodecSerializerSelection.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchEveryDeclaredMessageType = void 0;
+exports.rememberCodecSerializerSelections = rememberCodecSerializerSelections;
+exports.codecSerializerSelectionsOf = codecSerializerSelectionsOf;
+const selectionsByRegistry = new WeakMap();
+function rememberCodecSerializerSelections(serializers, selections) {
+    selectionsByRegistry.set(serializers, selections);
+    return serializers;
+}
+function codecSerializerSelectionsOf(serializers) {
+    return selectionsByRegistry.get(serializers);
+}
+const matchEveryDeclaredMessageType = () => true;
+exports.matchEveryDeclaredMessageType = matchEveryDeclaredMessageType;

package/dist/contracts/Configuration/Configs.d.ts

@@ -0,0 +1,23 @@
+import type { RoutingId } from '../Common';
+export interface ZLinkSocketConfig {
+    bind?: string;
+    connect?: string;
+    channelName?: string;
+    weight?: number;
+    sendHighWaterMark?: number;
+    receiveHighWaterMark?: number;
+    sendTimeoutMs?: number;
+}
+export interface ZLinkRouteConfig {
+    channelName: string;
+    endpoint: string;
+}
+export interface ZLinkOutboundRouteConfig {
+    targetNodeRid: RoutingId;
+    endpoint: string;
+}
+export interface ZLinkSpotPublisherConfig {
+    sendHighWaterMark: number;
+    sendTimeoutMs?: number;
+    lingerMs?: number;
+}

package/dist/contracts/Configuration/Configs.js

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

package/dist/contracts/Configuration/ConfigurationException.d.ts

@@ -0,0 +1,3 @@
+export declare class ZLinkConfigurationException extends Error {
+    constructor(message: string);
+}

package/dist/contracts/Configuration/ConfigurationException.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkConfigurationException = void 0;
+class ZLinkConfigurationException extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ZLinkConfigurationException';
+    }
+}
+exports.ZLinkConfigurationException = ZLinkConfigurationException;

package/dist/contracts/Configuration/Connections.d.ts

@@ -0,0 +1,5 @@
+export interface ZLinkEndpointConnections {
+    connect(endpoint: string): void;
+    disconnect(endpoint: string): void;
+    listConnections(): readonly string[];
+}

package/dist/contracts/Configuration/Connections.js

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

package/dist/contracts/Configuration/DiagnosticsValidation.d.ts

@@ -0,0 +1,3 @@
+import type { ZLinkMessageFlowLogMode } from '../Dispatch';
+export declare function requireMessageFlowLogMode(value: unknown): ZLinkMessageFlowLogMode;
+export declare function requireTraceSampleRate(value: number): number;

package/dist/contracts/Configuration/DiagnosticsValidation.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireMessageFlowLogMode = requireMessageFlowLogMode;
+exports.requireTraceSampleRate = requireTraceSampleRate;
+const ConfigurationException_1 = require("./ConfigurationException");
+const MESSAGE_FLOW_MODES = new Set([
+    'off',
+    'errors',
+    'normal',
+    'detailed'
+]);
+function requireMessageFlowLogMode(value) {
+    if (typeof value !== 'string' || !MESSAGE_FLOW_MODES.has(value)) {
+        throw new ConfigurationException_1.ZLinkConfigurationException("messageFlow must be one of 'off', 'errors', 'normal', or 'detailed'.");
+    }
+    return value;
+}
+function requireTraceSampleRate(value) {
+    if (!Number.isFinite(value) || value < 0 || value > 1) {
+        throw new ConfigurationException_1.ZLinkConfigurationException('traceSampleRate must be a finite number in 0..1.');
+    }
+    return value;
+}

package/dist/contracts/Configuration/EndpointNotation.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Deterministic endpoint-notation normalization (endpoint 표기 정책,
+ * doc/plan/endpoint-notation-policy.ko.md).
+ *
+ * `new URL()` cannot represent this domain: it throws on bracketed IPv6
+ * literals that carry a zone id (`tcp://[fe80::1%eth0]:80`, even with the
+ * zone id percent-escaped as `%25eth0`), and for non-special schemes like
+ * `tcp://`/`tls://` it does not lowercase the host and it re-encodes
+ * userinfo/query, which would violate the losslessness requirement below.
+ * This module parses the `scheme://[userinfo@]host[:port][/path][?query][#fragment]`
+ * grammar directly, bracket-aware, so it never resorts to `lastIndexOf(':')`
+ * to split host from port (that breaks on IPv6 literals).
+ *
+ * Normalization is applied once, at the point an endpoint is constructed or
+ * accepted from outside the process (config, wire, Location Store row,
+ * public connect/disconnect APIs). Everything downstream compares the
+ * resulting strings with plain `===`.
+ *
+ * Rules (policy 2.2), applied only to authority-bearing schemes
+ * (`tcp`, `tls`, `ws`, `wss` -- schemes whose grammar after `scheme://` is
+ * `host:port`):
+ *  - scheme: lowercased
+ *  - host: lowercased (IPv6 zone id is preserved verbatim, not lowercased --
+ *    interface names are case sensitive on Linux)
+ *  - IPv6 host: unified to bracketed form, zone id preserved
+ *  - port: decimal, leading zeros stripped
+ *  - path: trailing slash(es) stripped
+ *  - surrounding whitespace stripped
+ *
+ * Schemes without an authority -- `ipc://` is the one in use here, where
+ * what follows `scheme://` is a filesystem path, not a host -- only get
+ * scheme lowercasing and whitespace trimming. A path can be case sensitive
+ * and a trailing slash can be meaningful, so applying the host rules would
+ * change what the endpoint points at. This matches the C++ implementation
+ * (framework/languages/cpp/framework/src/runtime/transport/endpoint_notation.hpp).
+ *
+ * Normalization is lossless: userInfo, query, fragment and IPv6 zone id are
+ * preserved exactly as given. It is also idempotent:
+ * `normalizeEndpoint(normalizeEndpoint(x)) === normalizeEndpoint(x)`.
+ *
+ * DNS names are never resolved. `localhost` and `127.0.0.1` remain distinct
+ * endpoints (policy 2.1).
+ */
+export declare function normalizeEndpoint(endpoint: string): string;
+/**
+ * Extracts `{ host, port }` from a `scheme://[userinfo@]host[:port]...`
+ * endpoint whose scheme (case-insensitively) matches `expectedScheme`.
+ * `host` has IPv6 brackets stripped (zone id, if any, stays attached).
+ * `port` is `0` when absent. Returns `undefined` when the scheme doesn't
+ * match or the endpoint isn't parseable.
+ *
+ * IPv6-safe by construction (bracket-aware, never `lastIndexOf(':')`) --
+ * this replaces `new URL()`-based host/port extraction, which throws on a
+ * zone id (even percent-escaped) and so silently produced `undefined`/`0`
+ * for such endpoints.
+ */
+export declare function parseEndpointHostPort(endpoint: string, expectedScheme: string): {
+    host: string;
+    port: number;
+} | undefined;
+/**
+ * Builds a normalized `scheme://advertiseHost:port` endpoint from a bound
+ * endpoint, replacing only the host. Consolidates what used to be three
+ * near-identical, independently drifted implementations
+ * (channel-socket-registry, fanout-location-runtime, spot-node-runtime-manager)
+ * -- all matched via the same regex shape, but only one of the three
+ * accepted non-`tcp` schemes or was scheme-case-insensitive.
+ *
+ * Returns `undefined` when `boundEndpoint` is not a `scheme://host:port`
+ * endpoint, or (when `restrictToScheme` is given) when its scheme doesn't
+ * match after lowercasing -- callers translate that into their own
+ * capability-specific `ZLinkConfigurationException` message. Returns
+ * `boundEndpoint` normalized (unrestricted) when `advertiseHost` is
+ * undefined -- the common case, and the actual bound endpoint that ends up
+ * on the wire and in descriptors compared elsewhere.
+ */
+export declare function buildAdvertisedEndpoint(boundEndpoint: string, advertiseHost: string | undefined, restrictToScheme?: string): string | undefined;

package/dist/contracts/Configuration/EndpointNotation.js

@@ -0,0 +1,218 @@
+"use strict";
+/**
+ * Deterministic endpoint-notation normalization (endpoint 표기 정책,
+ * doc/plan/endpoint-notation-policy.ko.md).
+ *
+ * `new URL()` cannot represent this domain: it throws on bracketed IPv6
+ * literals that carry a zone id (`tcp://[fe80::1%eth0]:80`, even with the
+ * zone id percent-escaped as `%25eth0`), and for non-special schemes like
+ * `tcp://`/`tls://` it does not lowercase the host and it re-encodes
+ * userinfo/query, which would violate the losslessness requirement below.
+ * This module parses the `scheme://[userinfo@]host[:port][/path][?query][#fragment]`
+ * grammar directly, bracket-aware, so it never resorts to `lastIndexOf(':')`
+ * to split host from port (that breaks on IPv6 literals).
+ *
+ * Normalization is applied once, at the point an endpoint is constructed or
+ * accepted from outside the process (config, wire, Location Store row,
+ * public connect/disconnect APIs). Everything downstream compares the
+ * resulting strings with plain `===`.
+ *
+ * Rules (policy 2.2), applied only to authority-bearing schemes
+ * (`tcp`, `tls`, `ws`, `wss` -- schemes whose grammar after `scheme://` is
+ * `host:port`):
+ *  - scheme: lowercased
+ *  - host: lowercased (IPv6 zone id is preserved verbatim, not lowercased --
+ *    interface names are case sensitive on Linux)
+ *  - IPv6 host: unified to bracketed form, zone id preserved
+ *  - port: decimal, leading zeros stripped
+ *  - path: trailing slash(es) stripped
+ *  - surrounding whitespace stripped
+ *
+ * Schemes without an authority -- `ipc://` is the one in use here, where
+ * what follows `scheme://` is a filesystem path, not a host -- only get
+ * scheme lowercasing and whitespace trimming. A path can be case sensitive
+ * and a trailing slash can be meaningful, so applying the host rules would
+ * change what the endpoint points at. This matches the C++ implementation
+ * (framework/languages/cpp/framework/src/runtime/transport/endpoint_notation.hpp).
+ *
+ * Normalization is lossless: userInfo, query, fragment and IPv6 zone id are
+ * preserved exactly as given. It is also idempotent:
+ * `normalizeEndpoint(normalizeEndpoint(x)) === normalizeEndpoint(x)`.
+ *
+ * DNS names are never resolved. `localhost` and `127.0.0.1` remain distinct
+ * endpoints (policy 2.1).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeEndpoint = normalizeEndpoint;
+exports.parseEndpointHostPort = parseEndpointHostPort;
+exports.buildAdvertisedEndpoint = buildAdvertisedEndpoint;
+const SCHEME_PATTERN = /^([A-Za-z][A-Za-z0-9+.-]*):\/\/(.*)$/s;
+const AUTHORITY_SCHEMES = new Set(['tcp', 'tls', 'ws', 'wss']);
+function isAuthorityScheme(schemeLower) {
+    return AUTHORITY_SCHEMES.has(schemeLower);
+}
+function normalizeEndpoint(endpoint) {
+    const trimmed = endpoint.trim();
+    const schemeMatch = SCHEME_PATTERN.exec(trimmed);
+    if (schemeMatch === null) {
+        // Not a `scheme://...` endpoint (e.g. malformed input). Nothing in the
+        // policy defines normalization outside this grammar; leave it as-is
+        // (whitespace already stripped) rather than guessing.
+        return trimmed;
+    }
+    const scheme = schemeMatch[1].toLowerCase();
+    const rest = schemeMatch[2];
+    if (!isAuthorityScheme(scheme)) {
+        // Non-authority scheme (e.g. "ipc" -- a filesystem path follows, not a
+        // host) or an unknown scheme: only the scheme casing is a safe,
+        // lossless normalization. The remainder is opaque and returned
+        // byte-for-byte.
+        return `${scheme}://${rest}`;
+    }
+    const authorityEnd = findAuthorityEnd(rest);
+    const authority = rest.slice(0, authorityEnd);
+    const suffix = rest.slice(authorityEnd);
+    const atIndex = authority.lastIndexOf('@');
+    const userInfo = atIndex >= 0 ? authority.slice(0, atIndex + 1) : '';
+    const hostPort = atIndex >= 0 ? authority.slice(atIndex + 1) : authority;
+    const { host, port } = splitHostPort(hostPort);
+    const normalizedHost = normalizeHost(host);
+    const normalizedPort = normalizePort(port);
+    return `${scheme}://${userInfo}${normalizedHost}`
+        + (normalizedPort.length > 0 ? `:${normalizedPort}` : '')
+        + normalizeSuffix(suffix);
+}
+function findAuthorityEnd(rest) {
+    if (rest.startsWith('[')) {
+        const closeBracket = rest.indexOf(']');
+        if (closeBracket === -1) {
+            // Malformed (unterminated bracket); treat the remainder as authority.
+            return rest.length;
+        }
+        const tail = rest.slice(closeBracket);
+        const delimiter = /[/?#]/.exec(tail);
+        return delimiter === null ? rest.length : closeBracket + delimiter.index;
+    }
+    const delimiter = /[/?#]/.exec(rest);
+    return delimiter === null ? rest.length : delimiter.index;
+}
+function splitHostPort(hostPort) {
+    if (hostPort.startsWith('[')) {
+        const closeBracket = hostPort.indexOf(']');
+        if (closeBracket === -1) {
+            return { host: hostPort, port: '' };
+        }
+        const host = hostPort.slice(0, closeBracket + 1);
+        const afterBracket = hostPort.slice(closeBracket + 1);
+        const port = afterBracket.startsWith(':') ? afterBracket.slice(1) : '';
+        return { host, port };
+    }
+    const colonCount = (hostPort.match(/:/g) ?? []).length;
+    if (colonCount >= 2) {
+        // Unbracketed IPv6 literal (no port present, since a bracketed form is
+        // otherwise required to attach a port unambiguously). Unify to bracketed
+        // form -- never split on the "last colon" here, that corrupts IPv6.
+        return { host: `[${hostPort}]`, port: '' };
+    }
+    const colonIndex = hostPort.indexOf(':');
+    if (colonIndex === -1) {
+        return { host: hostPort, port: '' };
+    }
+    return { host: hostPort.slice(0, colonIndex), port: hostPort.slice(colonIndex + 1) };
+}
+function normalizeHost(host) {
+    if (host.startsWith('[') && host.endsWith(']')) {
+        const inner = host.slice(1, -1);
+        const zoneIndex = inner.indexOf('%');
+        if (zoneIndex === -1) {
+            return `[${inner.toLowerCase()}]`;
+        }
+        const address = inner.slice(0, zoneIndex).toLowerCase();
+        const zone = inner.slice(zoneIndex);
+        return `[${address}${zone}]`;
+    }
+    return host.toLowerCase();
+}
+function normalizePort(port) {
+    if (!/^\d+$/.test(port)) {
+        // Not a plain decimal port (empty, or something we shouldn't guess
+        // about); leave verbatim rather than risk corrupting it.
+        return port;
+    }
+    const stripped = port.replace(/^0+(?=\d)/, '');
+    return stripped;
+}
+/**
+ * Extracts `{ host, port }` from a `scheme://[userinfo@]host[:port]...`
+ * endpoint whose scheme (case-insensitively) matches `expectedScheme`.
+ * `host` has IPv6 brackets stripped (zone id, if any, stays attached).
+ * `port` is `0` when absent. Returns `undefined` when the scheme doesn't
+ * match or the endpoint isn't parseable.
+ *
+ * IPv6-safe by construction (bracket-aware, never `lastIndexOf(':')`) --
+ * this replaces `new URL()`-based host/port extraction, which throws on a
+ * zone id (even percent-escaped) and so silently produced `undefined`/`0`
+ * for such endpoints.
+ */
+function parseEndpointHostPort(endpoint, expectedScheme) {
+    const schemeMatch = SCHEME_PATTERN.exec(endpoint.trim());
+    if (schemeMatch === null)
+        return undefined;
+    if (schemeMatch[1].toLowerCase() !== expectedScheme)
+        return undefined;
+    const rest = schemeMatch[2];
+    const authorityEnd = findAuthorityEnd(rest);
+    const authority = rest.slice(0, authorityEnd);
+    const atIndex = authority.lastIndexOf('@');
+    const hostPort = atIndex >= 0 ? authority.slice(atIndex + 1) : authority;
+    const { host, port } = splitHostPort(hostPort);
+    const bareHost = host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
+    return {
+        host: bareHost,
+        port: /^\d+$/.test(port) ? Number(port) : 0
+    };
+}
+const ADVERTISE_SOURCE_PATTERN = /^([A-Za-z][A-Za-z0-9+.-]*):\/\/(?:\[[^\]]+\]|[^:]+):(\d+)$/;
+/**
+ * Builds a normalized `scheme://advertiseHost:port` endpoint from a bound
+ * endpoint, replacing only the host. Consolidates what used to be three
+ * near-identical, independently drifted implementations
+ * (channel-socket-registry, fanout-location-runtime, spot-node-runtime-manager)
+ * -- all matched via the same regex shape, but only one of the three
+ * accepted non-`tcp` schemes or was scheme-case-insensitive.
+ *
+ * Returns `undefined` when `boundEndpoint` is not a `scheme://host:port`
+ * endpoint, or (when `restrictToScheme` is given) when its scheme doesn't
+ * match after lowercasing -- callers translate that into their own
+ * capability-specific `ZLinkConfigurationException` message. Returns
+ * `boundEndpoint` normalized (unrestricted) when `advertiseHost` is
+ * undefined -- the common case, and the actual bound endpoint that ends up
+ * on the wire and in descriptors compared elsewhere.
+ */
+function buildAdvertisedEndpoint(boundEndpoint, advertiseHost, restrictToScheme) {
+    if (advertiseHost === undefined)
+        return normalizeEndpoint(boundEndpoint);
+    const match = ADVERTISE_SOURCE_PATTERN.exec(boundEndpoint);
+    if (match === null)
+        return undefined;
+    const scheme = match[1].toLowerCase();
+    if (restrictToScheme !== undefined && scheme !== restrictToScheme)
+        return undefined;
+    const host = advertiseHost.includes(':') && !advertiseHost.startsWith('[')
+        ? `[${advertiseHost}]`
+        : advertiseHost;
+    return normalizeEndpoint(`${scheme}://${host}:${match[2]}`);
+}
+function normalizeSuffix(suffix) {
+    if (suffix.length === 0) {
+        return suffix;
+    }
+    const hashIndex = suffix.indexOf('#');
+    const beforeFragment = hashIndex >= 0 ? suffix.slice(0, hashIndex) : suffix;
+    const fragment = hashIndex >= 0 ? suffix.slice(hashIndex) : '';
+    const queryIndex = beforeFragment.indexOf('?');
+    const path = queryIndex >= 0 ? beforeFragment.slice(0, queryIndex) : beforeFragment;
+    const query = queryIndex >= 0 ? beforeFragment.slice(queryIndex) : '';
+    const normalizedPath = path.replace(/\/+$/, '');
+    return `${normalizedPath}${query}${fragment}`;
+}

package/dist/contracts/Configuration/InternalDefaults.d.ts

@@ -0,0 +1,7 @@
+/** Default complete header plus payload size accepted by a StreamNode. */
+export declare const DEFAULT_STREAM_NODE_MAX_MESSAGE_SIZE: number;
+/** Defaults shared by registration normalization and the runtime worker pool. */
+export declare const DEFAULT_WORKER_MIN_THREADS = 0;
+export declare const DEFAULT_WORKER_IDLE_TIMEOUT_MS = 30000;
+export declare const DEFAULT_WORKER_QUEUE_LENGTH = 1024;
+export declare function defaultWorkerMaxThreads(): number;