@zlink-systems/framework 0.10.0

package/dist/runtime/foundation/service-topology-registry.d.ts

@@ -0,0 +1,68 @@
+export type ServiceNodeState = 'preparing' | 'serving' | 'retiring' | 'draining' | 'stopped' | 'error';
+export type ServiceObjectRole = 'none' | 'client' | 'server';
+export interface ServiceChannelDescriptor {
+    readonly name: string;
+    readonly weight: number;
+}
+export interface ServiceNodeDescriptor {
+    readonly meshName: string;
+    readonly nodeRoutingId: string;
+    readonly lifecycleGeneration: bigint;
+    readonly descriptorRevision: bigint;
+    readonly advertisedEndpoint: string;
+    readonly channels: readonly ServiceChannelDescriptor[];
+    readonly state: ServiceNodeState;
+    readonly securityIdentity: string;
+    readonly applicationVersion: bigint;
+    readonly maintenanceWave?: string;
+    readonly protocolCapabilities: readonly string[];
+    readonly objectRole: ServiceObjectRole;
+    readonly placementWeight: number;
+    readonly activeCapacityLimit: number;
+    readonly pendingCapacityLimit: number;
+    readonly activeCapacityUsed: number;
+    readonly pendingCapacityUsed: number;
+}
+export interface AdmittedServicePeer {
+    readonly descriptor: ServiceNodeDescriptor;
+    readonly connectionId: string;
+    readonly connectionDiscriminator: string;
+}
+export interface ServicePeerAdmissionExpectation {
+    readonly endpoint?: string;
+    readonly securityIdentity?: string;
+    readonly lifecycleGeneration?: bigint;
+}
+export type PeerAdmissionResult = 'admitted' | 'notRequired' | 'meshMismatch' | 'invalidDescriptor' | 'staleDescriptor';
+export type ServiceObjectPlacementStatus = 'available' | 'unsupported' | 'capacity' | 'unavailable';
+/** Owns immutable peer snapshots and fences late physical-connection events. */
+export declare class ServiceTopologyRegistry {
+    private local;
+    private readonly peersByRid;
+    private readonly notRequiredByRid;
+    private readonly knownByRid;
+    private readonly selections;
+    constructor(local: ServiceNodeDescriptor);
+    localDescriptor(): ServiceNodeDescriptor;
+    publishLocal(descriptor: ServiceNodeDescriptor): void;
+    admit(descriptor: ServiceNodeDescriptor, connectionId: string, expected?: ServicePeerAdmissionExpectation, connectionDiscriminator?: string): PeerAdmissionResult;
+    disconnect(nodeRoutingId: string, connectionId: string): boolean;
+    peer(nodeRoutingId: string): AdmittedServicePeer | undefined;
+    peers(): readonly AdmittedServicePeer[];
+    private peersCore;
+    notRequiredPeers(): readonly ServiceNodeDescriptor[];
+    replaceDiscoveredNotRequired(descriptors: readonly ServiceNodeDescriptor[]): void;
+    markNotRequired(descriptor: ServiceNodeDescriptor): void;
+    forgetNotRequired(nodeRoutingId: string): void;
+    knownDescriptor(nodeRoutingId: string): ServiceNodeDescriptor | undefined;
+    private remember;
+    selectChannel(channelName: string, isReady?: (peer: AdmittedServicePeer) => boolean): AdmittedServicePeer | undefined;
+    selectPlacement(isReady?: (peer: AdmittedServicePeer) => boolean): AdmittedServicePeer | undefined;
+    selectObjectPlacement(stableType: string, isReady?: (descriptor: ServiceNodeDescriptor) => boolean): ServiceNodeDescriptor | undefined;
+    objectPlacementStatus(stableType: string, isReady?: (descriptor: ServiceNodeDescriptor) => boolean): ServiceObjectPlacementStatus;
+    instanceSpotPlacementTypes(): readonly string[];
+    private selectWeightedCycle;
+    private rebuildSelections;
+}
+export declare function validateDescriptor(descriptor: ServiceNodeDescriptor): void;
+export declare function sameServiceNodeDescriptor(left: ServiceNodeDescriptor, right: ServiceNodeDescriptor): boolean;

package/dist/runtime/foundation/service-topology-registry.js

@@ -0,0 +1,393 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceTopologyRegistry = void 0;
+exports.validateDescriptor = validateDescriptor;
+exports.sameServiceNodeDescriptor = sameServiceNodeDescriptor;
+const route_mesh_connection_policy_1 = require("./route-mesh-connection-policy");
+const service_weighted_selection_1 = require("./service-weighted-selection");
+const service_wire_constants_generated_1 = require("./service-wire-constants.generated");
+const REQUIRED_CAPABILITY = service_wire_constants_generated_1.SERVICE_WIRE_REQUIRED_CAPABILITY;
+const MAX_CAPACITY = 0x7fff_ffff;
+const MAX_PUBLIC_WEIGHT = 10_000;
+/** Owns immutable peer snapshots and fences late physical-connection events. */
+class ServiceTopologyRegistry {
+    local;
+    peersByRid = new Map();
+    notRequiredByRid = new Map();
+    knownByRid = new Map();
+    selections = new Map();
+    constructor(local) {
+        validateDescriptor(local);
+        this.local = cloneDescriptor(local);
+    }
+    localDescriptor() {
+        return cloneDescriptor(this.local);
+    }
+    publishLocal(descriptor) {
+        validateDescriptor(descriptor);
+        if (descriptor.meshName !== this.local.meshName
+            || descriptor.nodeRoutingId !== this.local.nodeRoutingId
+            || descriptor.lifecycleGeneration !== this.local.lifecycleGeneration) {
+            throw new TypeError('Published descriptor changes the local node identity.');
+        }
+        if (descriptor.descriptorRevision <= this.local.descriptorRevision) {
+            throw new RangeError('Published descriptor revision must increase.');
+        }
+        this.local = cloneDescriptor(descriptor);
+        for (const [nodeRoutingId, remote] of this.notRequiredByRid) {
+            if (!(0, route_mesh_connection_policy_1.descriptorConnectionNotRequired)(this.local, remote)) {
+                this.notRequiredByRid.delete(nodeRoutingId);
+            }
+        }
+        this.rebuildSelections();
+    }
+    admit(descriptor, connectionId, expected, connectionDiscriminator = connectionId) {
+        try {
+            validateDescriptor(descriptor);
+            requireText(connectionId, 'connectionId');
+            requireText(connectionDiscriminator, 'connectionDiscriminator');
+        }
+        catch (error) {
+            return 'invalidDescriptor';
+        }
+        if (descriptor.meshName !== this.local.meshName)
+            return 'meshMismatch';
+        if (descriptor.nodeRoutingId === this.local.nodeRoutingId)
+            return 'invalidDescriptor';
+        if ((expected?.endpoint !== undefined
+            && descriptor.advertisedEndpoint !== expected.endpoint)
+            || (expected?.securityIdentity !== undefined
+                && descriptor.securityIdentity !== expected.securityIdentity)
+            || (expected?.lifecycleGeneration !== undefined
+                && descriptor.lifecycleGeneration !== expected.lifecycleGeneration)) {
+            return 'invalidDescriptor';
+        }
+        if ((0, route_mesh_connection_policy_1.descriptorConnectionNotRequired)(this.local, descriptor)) {
+            this.peersByRid.delete(descriptor.nodeRoutingId);
+            this.remember(descriptor);
+            this.notRequiredByRid.set(descriptor.nodeRoutingId, cloneDescriptor(descriptor));
+            this.rebuildSelections();
+            return 'notRequired';
+        }
+        this.notRequiredByRid.delete(descriptor.nodeRoutingId);
+        const current = this.peersByRid.get(descriptor.nodeRoutingId);
+        if (current !== undefined
+            && current.descriptor.lifecycleGeneration === descriptor.lifecycleGeneration
+            && descriptor.descriptorRevision > current.descriptor.descriptorRevision
+            && !sameImmutableDescriptor(current.descriptor, descriptor)) {
+            return 'invalidDescriptor';
+        }
+        if (current !== undefined
+            && current.descriptor.lifecycleGeneration === descriptor.lifecycleGeneration
+            && (current.descriptor.descriptorRevision > descriptor.descriptorRevision
+                || (current.descriptor.descriptorRevision === descriptor.descriptorRevision
+                    && !sameServiceNodeDescriptor(current.descriptor, descriptor)))) {
+            return 'staleDescriptor';
+        }
+        if (current !== undefined
+            && current.descriptor.lifecycleGeneration === descriptor.lifecycleGeneration
+            && current.descriptor.descriptorRevision === descriptor.descriptorRevision
+            && sameServiceNodeDescriptor(current.descriptor, descriptor)
+            && current.connectionId !== connectionId
+            // A fallback candidate is only a logical placeholder. Once the
+            // monitor reports the physical connection, its evidence supersedes
+            // candidate ordering so the request path uses the native route.
+            && !(isUnmonitoredConnectionId(current.connectionId)
+                && !isUnmonitoredConnectionId(connectionId))
+            && compareConnectionCandidate(current.connectionDiscriminator, current.connectionId, connectionDiscriminator, connectionId) <= 0) {
+            // Both manual directions can reach admission. The same comparison on
+            // every retry keeps one physical candidate instead of replacing it in
+            // arrival order.
+            return 'staleDescriptor';
+        }
+        this.peersByRid.set(descriptor.nodeRoutingId, {
+            descriptor: cloneDescriptor(descriptor),
+            connectionId,
+            connectionDiscriminator
+        });
+        this.remember(descriptor);
+        this.rebuildSelections();
+        return 'admitted';
+    }
+    disconnect(nodeRoutingId, connectionId) {
+        const current = this.peersByRid.get(nodeRoutingId);
+        if (current === undefined || current.connectionId !== connectionId)
+            return false;
+        this.peersByRid.delete(nodeRoutingId);
+        this.rebuildSelections();
+        return true;
+    }
+    peer(nodeRoutingId) {
+        const peer = this.peersByRid.get(nodeRoutingId);
+        return peer === undefined ? undefined : clonePeer(peer);
+    }
+    peers() {
+        return this.peersCore();
+    }
+    peersCore() {
+        return [...this.peersByRid.values()]
+            .sort((left, right) => compareOrdinal(left.descriptor.nodeRoutingId, right.descriptor.nodeRoutingId))
+            .map(clonePeer);
+    }
+    notRequiredPeers() {
+        return [...this.notRequiredByRid.values()]
+            .sort((left, right) => compareOrdinal(left.nodeRoutingId, right.nodeRoutingId))
+            .map(cloneDescriptor);
+    }
+    replaceDiscoveredNotRequired(descriptors) {
+        const next = new Map();
+        for (const descriptor of descriptors) {
+            validateDescriptor(descriptor);
+            if (descriptor.meshName === this.local.meshName
+                && descriptor.nodeRoutingId !== this.local.nodeRoutingId
+                && (0, route_mesh_connection_policy_1.descriptorConnectionNotRequired)(this.local, descriptor)) {
+                next.set(descriptor.nodeRoutingId, cloneDescriptor(descriptor));
+            }
+        }
+        this.notRequiredByRid.clear();
+        for (const [nodeRoutingId, descriptor] of next) {
+            this.notRequiredByRid.set(nodeRoutingId, descriptor);
+            this.remember(descriptor);
+        }
+        this.rebuildSelections();
+    }
+    markNotRequired(descriptor) {
+        validateDescriptor(descriptor);
+        if (descriptor.meshName !== this.local.meshName
+            || descriptor.nodeRoutingId === this.local.nodeRoutingId
+            || !(0, route_mesh_connection_policy_1.descriptorConnectionNotRequired)(this.local, descriptor)) {
+            return;
+        }
+        this.peersByRid.delete(descriptor.nodeRoutingId);
+        this.remember(descriptor);
+        this.notRequiredByRid.set(descriptor.nodeRoutingId, cloneDescriptor(descriptor));
+        this.rebuildSelections();
+    }
+    forgetNotRequired(nodeRoutingId) {
+        if (this.notRequiredByRid.delete(nodeRoutingId))
+            this.rebuildSelections();
+    }
+    knownDescriptor(nodeRoutingId) {
+        const admitted = this.peersByRid.get(nodeRoutingId)?.descriptor;
+        const descriptor = admitted
+            ?? this.notRequiredByRid.get(nodeRoutingId)
+            ?? this.knownByRid.get(nodeRoutingId);
+        return descriptor === undefined ? undefined : cloneDescriptor(descriptor);
+    }
+    remember(descriptor) {
+        const current = this.knownByRid.get(descriptor.nodeRoutingId);
+        if (current === undefined
+            || descriptor.lifecycleGeneration !== current.lifecycleGeneration
+            || (descriptor.lifecycleGeneration === current.lifecycleGeneration
+                && descriptor.descriptorRevision >= current.descriptorRevision)) {
+            this.knownByRid.set(descriptor.nodeRoutingId, cloneDescriptor(descriptor));
+        }
+    }
+    selectChannel(channelName, isReady = () => true) {
+        requireText(channelName, 'channelName');
+        return this.selectWeightedCycle(`channel:${channelName}`, () => {
+            const local = {
+                descriptor: cloneDescriptor(this.local),
+                connectionId: 'local',
+                connectionDiscriminator: 'local'
+            };
+            return [local, ...this.peersByRid.values()].map(peer => ({
+                peer: clonePeer(peer),
+                channel: findChannel(peer.descriptor, channelName)
+            })).filter((value) => value.channel !== undefined
+                && value.peer.descriptor.state === 'serving'
+                && value.channel.weight > 0);
+        }, value => value.channel.weight, value => value.peer.descriptor.nodeRoutingId, (left, right) => compareOrdinal(left.peer.descriptor.nodeRoutingId, right.peer.descriptor.nodeRoutingId), value => isReady(value.peer))?.peer;
+    }
+    selectPlacement(isReady = () => true) {
+        return this.selectWeightedCycle('placement', () => [...this.peersByRid.values()].filter(peer => {
+            const descriptor = peer.descriptor;
+            return descriptor.state === 'serving'
+                && descriptor.objectRole === 'server'
+                && descriptor.placementWeight > 0
+                && descriptor.activeCapacityUsed < descriptor.activeCapacityLimit
+                && descriptor.pendingCapacityUsed < descriptor.pendingCapacityLimit;
+        }).map(clonePeer), peer => peer.descriptor.placementWeight, peer => peer.descriptor.nodeRoutingId, (left, right) => compareOrdinal(left.descriptor.nodeRoutingId, right.descriptor.nodeRoutingId), isReady);
+    }
+    selectObjectPlacement(stableType, isReady = () => true) {
+        requireText(stableType, 'stableType');
+        return this.selectWeightedCycle(`object:${stableType}`, () => {
+            const capability = `object-type:${stableType}`;
+            return [this.local, ...this.peersByRid.values()].map(value => 'descriptor' in value ? value.descriptor : value).filter(descriptor => descriptor.state === 'serving'
+                && descriptor.objectRole === 'server'
+                && descriptor.placementWeight > 0
+                && descriptor.activeCapacityUsed < descriptor.activeCapacityLimit
+                && descriptor.pendingCapacityUsed < descriptor.pendingCapacityLimit
+                && descriptor.protocolCapabilities.includes(capability)).map(cloneDescriptor);
+        }, descriptor => descriptor.placementWeight, descriptor => descriptor.nodeRoutingId, (left, right) => compareOrdinal(left.nodeRoutingId, right.nodeRoutingId), isReady);
+    }
+    objectPlacementStatus(stableType, isReady = () => true) {
+        requireText(stableType, 'stableType');
+        const capability = `object-type:${stableType}`;
+        const supported = [this.local, ...[...this.peersByRid.values()].map(peer => peer.descriptor)]
+            .filter(descriptor => descriptor.state === 'serving'
+            && descriptor.objectRole === 'server'
+            && descriptor.protocolCapabilities.includes(capability));
+        if (supported.length === 0)
+            return 'unsupported';
+        const withCapacity = supported.filter(descriptor => descriptor.activeCapacityUsed < descriptor.activeCapacityLimit
+            && descriptor.pendingCapacityUsed < descriptor.pendingCapacityLimit);
+        if (withCapacity.length === 0)
+            return 'capacity';
+        const weighted = withCapacity.filter(descriptor => descriptor.placementWeight > 0);
+        if (weighted.length === 0)
+            return 'unsupported';
+        return weighted.some(isReady) ? 'available' : 'unavailable';
+    }
+    instanceSpotPlacementTypes() {
+        const prefix = 'instance-spot-type:';
+        return [...new Set([
+                this.local,
+                ...this.peersCore().map(peer => peer.descriptor)
+            ]
+                .filter(descriptor => descriptor.state === 'serving'
+                && descriptor.objectRole === 'server')
+                .flatMap(descriptor => descriptor.protocolCapabilities)
+                .filter(capability => capability.startsWith(prefix))
+                .map(capability => capability.slice(prefix.length))
+                .filter(stableType => stableType.length > 0))]
+            .sort();
+    }
+    selectWeightedCycle(key, eligible, weight, identity, compare, accept = () => true) {
+        let entry = this.selections.get(key);
+        if (entry === undefined) {
+            const selection = new service_weighted_selection_1.SmoothWeightedSelection(() => eligible()
+                .map(value => ({
+                value,
+                id: identity(value),
+                weight: weight(value)
+            }))
+                .sort((left, right) => compare(left.value, right.value)));
+            entry = { selection };
+            this.selections.set(key, entry);
+        }
+        return entry.selection.select(value => accept(value));
+    }
+    rebuildSelections() {
+        for (const entry of this.selections.values())
+            entry.selection.rebuild();
+    }
+}
+exports.ServiceTopologyRegistry = ServiceTopologyRegistry;
+function validateDescriptor(descriptor) {
+    requireText(descriptor.meshName, 'meshName');
+    requireText(descriptor.nodeRoutingId, 'nodeRoutingId');
+    requireText(descriptor.advertisedEndpoint, 'advertisedEndpoint');
+    requireText(descriptor.securityIdentity, 'securityIdentity');
+    if (descriptor.lifecycleGeneration <= 0n || descriptor.descriptorRevision <= 0n) {
+        throw new RangeError('Lifecycle generation and descriptor revision must be non-zero.');
+    }
+    if (descriptor.applicationVersion < 0n) {
+        throw new RangeError('Descriptor application version is invalid.');
+    }
+    if (descriptor.maintenanceWave !== undefined) {
+        requireText(descriptor.maintenanceWave, 'maintenanceWave');
+        if (Buffer.byteLength(descriptor.maintenanceWave, 'utf8') > 255) {
+            throw new RangeError('maintenanceWave must not exceed 255 UTF-8 bytes.');
+        }
+    }
+    validatePublicWeight(descriptor.placementWeight, 'placementWeight');
+    validateCapacity(descriptor.activeCapacityLimit, false, 'activeCapacityLimit');
+    validateCapacity(descriptor.pendingCapacityLimit, true, 'pendingCapacityLimit');
+    validateCapacity(descriptor.activeCapacityUsed, true, 'activeCapacityUsed');
+    validateCapacity(descriptor.pendingCapacityUsed, true, 'pendingCapacityUsed');
+    if (descriptor.activeCapacityUsed > descriptor.activeCapacityLimit
+        || descriptor.pendingCapacityUsed > descriptor.pendingCapacityLimit) {
+        throw new RangeError('Descriptor capacity use exceeds its limit.');
+    }
+    validateSortedUnique(descriptor.channels, channel => {
+        requireText(channel.name, 'channel.name');
+        validatePublicWeight(channel.weight, 'channel.weight');
+        return channel.name;
+    }, 'channels');
+    validateSortedUnique(descriptor.protocolCapabilities, capability => {
+        requireText(capability, 'protocol capability');
+        return capability;
+    }, 'protocolCapabilities');
+    if (!descriptor.protocolCapabilities.includes(REQUIRED_CAPABILITY)) {
+        throw new TypeError(`Descriptor requires capability '${REQUIRED_CAPABILITY}'.`);
+    }
+}
+function validateCapacity(value, allowZero, field) {
+    if (!Number.isInteger(value) || value < (allowZero ? 0 : 1) || value > MAX_CAPACITY) {
+        throw new RangeError(`${field} is outside its supported range.`);
+    }
+}
+function validatePublicWeight(value, field) {
+    if (!Number.isInteger(value) || value < 0 || value > MAX_PUBLIC_WEIGHT) {
+        throw new RangeError(`${field} must be an integer in 0..10000.`);
+    }
+}
+function validateSortedUnique(values, key, field) {
+    let previous;
+    for (const value of values) {
+        const current = key(value);
+        if (previous !== undefined && previous >= current) {
+            throw new TypeError(`${field} must be sorted and unique.`);
+        }
+        previous = current;
+    }
+}
+function findChannel(descriptor, channelName) {
+    return descriptor.channels.find(channel => channel.name === channelName);
+}
+function requireText(value, field) {
+    if (value.length === 0 || value.includes('\0')) {
+        throw new TypeError(`${field} must be non-empty text without NUL.`);
+    }
+}
+function cloneDescriptor(descriptor) {
+    return {
+        ...descriptor,
+        channels: descriptor.channels.map(channel => ({ ...channel })),
+        protocolCapabilities: [...descriptor.protocolCapabilities]
+    };
+}
+function clonePeer(peer) {
+    return {
+        descriptor: cloneDescriptor(peer.descriptor),
+        connectionId: peer.connectionId,
+        connectionDiscriminator: peer.connectionDiscriminator
+    };
+}
+function sameServiceNodeDescriptor(left, right) {
+    return JSON.stringify(toComparable(left)) === JSON.stringify(toComparable(right));
+}
+function sameImmutableDescriptor(left, right) {
+    return left.advertisedEndpoint === right.advertisedEndpoint
+        && left.securityIdentity === right.securityIdentity
+        && left.applicationVersion === right.applicationVersion
+        && arraysEqual(left.protocolCapabilities, right.protocolCapabilities)
+        && left.objectRole === right.objectRole
+        && left.activeCapacityLimit === right.activeCapacityLimit
+        && left.pendingCapacityLimit === right.pendingCapacityLimit
+        && left.channels.length === right.channels.length
+        && left.channels.every((channel, index) => channel.name === right.channels[index]?.name);
+}
+function arraysEqual(left, right) {
+    return left.length === right.length
+        && left.every((value, index) => value === right[index]);
+}
+function isUnmonitoredConnectionId(connectionId) {
+    return connectionId.startsWith('unmonitored:');
+}
+function compareConnectionCandidate(leftDiscriminator, leftId, rightDiscriminator, rightId) {
+    const discriminator = compareOrdinal(leftDiscriminator, rightDiscriminator);
+    return discriminator === 0 ? compareOrdinal(leftId, rightId) : discriminator;
+}
+function compareOrdinal(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function toComparable(descriptor) {
+    return {
+        ...descriptor,
+        lifecycleGeneration: descriptor.lifecycleGeneration.toString(),
+        descriptorRevision: descriptor.descriptorRevision.toString(),
+        applicationVersion: descriptor.applicationVersion.toString()
+    };
+}

package/dist/runtime/foundation/service-weighted-selection.d.ts

@@ -0,0 +1,14 @@
+export interface ServiceWeightedSelectionCandidate<T> {
+    readonly value: T;
+    readonly id: string;
+    readonly weight: number;
+}
+/** Owns cumulative smooth-weighted selection state without exposing it to topology callers. */
+export declare class SmoothWeightedSelection<T> {
+    private readonly candidateProvider;
+    private readonly current;
+    private plan;
+    constructor(candidateProvider: () => readonly ServiceWeightedSelectionCandidate<T>[]);
+    rebuild(): void;
+    select(accept?: (value: T) => boolean): T | undefined;
+}

package/dist/runtime/foundation/service-weighted-selection.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SmoothWeightedSelection = void 0;
+const MAX_CYCLE_SEARCH_STEPS = 4_096;
+const MAX_CYCLE_SEARCH_MS = 10;
+/** Owns cumulative smooth-weighted selection state without exposing it to topology callers. */
+class SmoothWeightedSelection {
+    candidateProvider;
+    current = new Map();
+    plan;
+    constructor(candidateProvider) {
+        this.candidateProvider = candidateProvider;
+        this.plan = emptyCycle();
+        this.rebuild();
+    }
+    rebuild() {
+        if (this.plan.kind === 'cycle' && this.plan.values.length > 0) {
+            replaceState(this.current, this.plan.states[this.plan.cursor]);
+        }
+        this.plan = buildSelectionPlan(this.candidateProvider(), this.current);
+    }
+    select(accept = () => true) {
+        if (this.plan.kind === 'direct') {
+            for (let attempts = 0; attempts < this.plan.candidates.length; attempts += 1) {
+                const selected = selectDirect(this.plan.candidates, this.current);
+                if (selected !== undefined && accept(selected))
+                    return selected;
+            }
+            return undefined;
+        }
+        if (this.plan.values.length === 0)
+            return undefined;
+        for (let attempts = 0; attempts < this.plan.values.length; attempts += 1) {
+            const cursor = this.plan.cursor;
+            const selected = this.plan.values[cursor];
+            const nextCursor = cursor + 1 < this.plan.values.length
+                ? cursor + 1
+                : this.plan.cycleStart;
+            this.plan.cursor = nextCursor;
+            if (accept(selected))
+                return selected;
+        }
+        return undefined;
+    }
+}
+exports.SmoothWeightedSelection = SmoothWeightedSelection;
+function buildSelectionPlan(eligible, current) {
+    const candidates = eligible.map(candidate => ({
+        ...candidate,
+        weight: BigInt(candidate.weight)
+    }));
+    const total = candidates.reduce((sum, candidate) => sum + candidate.weight, 0n);
+    replaceState(current, new Map(candidates.map(candidate => [
+        candidate.id,
+        current.get(candidate.id) ?? 0n
+    ])));
+    if (total === 0n)
+        return emptyCycle();
+    const values = [];
+    const states = [];
+    const seen = new Map();
+    const working = new Map(current);
+    const startedAt = performance.now();
+    for (;;) {
+        if (values.length >= MAX_CYCLE_SEARCH_STEPS
+            || performance.now() - startedAt >= MAX_CYCLE_SEARCH_MS) {
+            return { kind: 'direct', candidates };
+        }
+        const stateKey = candidates
+            .map(candidate => `${candidate.id}\u0000${working.get(candidate.id) ?? 0n}`)
+            .join('\u0001');
+        const cycleStart = seen.get(stateKey);
+        if (cycleStart !== undefined) {
+            return {
+                kind: 'cycle',
+                values: Object.freeze(values),
+                states: Object.freeze(states),
+                cycleStart,
+                cursor: 0
+            };
+        }
+        seen.set(stateKey, values.length);
+        states.push(new Map(working));
+        let selected = candidates[0];
+        let selectedCurrent = working.get(selected.id) + selected.weight;
+        for (const candidate of candidates) {
+            const next = working.get(candidate.id) + candidate.weight;
+            working.set(candidate.id, next);
+            if (next > selectedCurrent) {
+                selected = candidate;
+                selectedCurrent = next;
+            }
+        }
+        working.set(selected.id, working.get(selected.id) - total);
+        values.push(selected.value);
+    }
+}
+function emptyCycle() {
+    return {
+        kind: 'cycle',
+        values: Object.freeze([]),
+        states: Object.freeze([]),
+        cycleStart: 0,
+        cursor: 0
+    };
+}
+function selectDirect(candidates, current) {
+    if (candidates.length === 0)
+        return undefined;
+    const total = candidates.reduce((sum, candidate) => sum + candidate.weight, 0n);
+    let selected = candidates[0];
+    let selectedCurrent = current.get(selected.id) + selected.weight;
+    for (const candidate of candidates) {
+        const next = current.get(candidate.id) + candidate.weight;
+        current.set(candidate.id, next);
+        if (next > selectedCurrent) {
+            selected = candidate;
+            selectedCurrent = next;
+        }
+    }
+    current.set(selected.id, current.get(selected.id) - total);
+    return selected.value;
+}
+function replaceState(target, source) {
+    target.clear();
+    for (const [key, value] of source)
+        target.set(key, value);
+}

package/dist/runtime/foundation/service-wire-binary-primitives.d.ts

@@ -0,0 +1,10 @@
+import type { RoutingId } from '../../contracts';
+export type ServiceWireInvalid = (message: string) => never;
+/** Encodes text without silently replacing an unpaired UTF-16 surrogate. */
+export declare function encodeCanonicalServiceWireText(value: string, field: string, maximumBytes: number, invalid: ServiceWireInvalid): Buffer;
+/** Decodes schema text and rejects Node's replacement-character fallback. */
+export declare function decodeCanonicalServiceWireText(bytes: Uint8Array, field: string, invalid: ServiceWireInvalid): string;
+/** Preserves the schema's binary-safe RoutingId bytes. */
+export declare function encodeServiceWireRoutingId(value: RoutingId, field: string, maximumBytes: number, invalid: ServiceWireInvalid): Buffer;
+/** Returns printable UTF-8 as a string and otherwise retains an opaque byte identity. */
+export declare function decodeServiceWireRoutingId(bytes: Uint8Array, field: string, maximumBytes: number, invalid: ServiceWireInvalid): RoutingId;

package/dist/runtime/foundation/service-wire-binary-primitives.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeCanonicalServiceWireText = encodeCanonicalServiceWireText;
+exports.decodeCanonicalServiceWireText = decodeCanonicalServiceWireText;
+exports.encodeServiceWireRoutingId = encodeServiceWireRoutingId;
+exports.decodeServiceWireRoutingId = decodeServiceWireRoutingId;
+const routing_id_1 = require("../routing-id");
+/** Encodes text without silently replacing an unpaired UTF-16 surrogate. */
+function encodeCanonicalServiceWireText(value, field, maximumBytes, invalid) {
+    const bytes = Buffer.from(value, 'utf8');
+    if (bytes.byteLength < 1
+        || bytes.byteLength > maximumBytes
+        || value.includes('\0')
+        || bytes.toString('utf8') !== value) {
+        invalid(`${field} must be 1..${maximumBytes} canonical UTF-8 bytes without NUL.`);
+    }
+    return bytes;
+}
+/** Decodes schema text and rejects Node's replacement-character fallback. */
+function decodeCanonicalServiceWireText(bytes, field, invalid) {
+    const encoded = Buffer.from(bytes);
+    const value = encoded.toString('utf8');
+    if (value.includes('\0')
+        || !Buffer.from(value, 'utf8').equals(encoded)) {
+        invalid(`${field} is not canonical UTF-8 without NUL.`);
+    }
+    return value;
+}
+/** Preserves the schema's binary-safe RoutingId bytes. */
+function encodeServiceWireRoutingId(value, field, maximumBytes, invalid) {
+    let bytes;
+    try {
+        bytes = Buffer.from((0, routing_id_1.encodeRoutingIdStorageHex)(value), 'hex');
+    }
+    catch (error) {
+        invalid(`${field} is not a valid RoutingId: ${errorMessage(error)}`);
+    }
+    if (bytes.byteLength < 1 || bytes.byteLength > maximumBytes) {
+        invalid(`${field} must be 1..${maximumBytes} opaque bytes.`);
+    }
+    return bytes;
+}
+/** Returns printable UTF-8 as a string and otherwise retains an opaque byte identity. */
+function decodeServiceWireRoutingId(bytes, field, maximumBytes, invalid) {
+    const encoded = Buffer.from(bytes);
+    if (encoded.byteLength < 1 || encoded.byteLength > maximumBytes) {
+        invalid(`${field} must be 1..${maximumBytes} opaque bytes.`);
+    }
+    return (0, routing_id_1.decodeRoutingId)(encoded.toString('utf8'), encoded.toString('hex'));
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}