@zlink-systems/framework 0.10.0

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

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceDiscoveryRegistry = void 0;
+/** Dedicated discovery state; fanout publishers never reuse RouteMesh peer rows. */
+class ServiceDiscoveryRegistry {
+    clientServers = new Map();
+    fanoutPublishers = new Map();
+    clientServerSelections = new Map();
+    admitClientServer(descriptor, connectionId) {
+        validateClientServer(descriptor);
+        const key = `${descriptor.channelName}\0${descriptor.serverRoutingId}`;
+        const current = this.clientServers.get(key);
+        if (current !== undefined
+            && current.descriptor.state === 'disconnected'
+            && sameClientServerDescriptorExceptState(current.descriptor, descriptor)) {
+            this.clientServers.set(key, { descriptor: { ...descriptor }, connectionId });
+            this.invalidateClientServerCandidates(descriptor.channelName);
+            return true;
+        }
+        const admitted = this.admit(this.clientServers, key, descriptor, connectionId);
+        if (admitted)
+            this.invalidateClientServerCandidates(descriptor.channelName);
+        return admitted;
+    }
+    markClientServerDisconnected(channelName, serverRoutingId, connectionId) {
+        const key = `${channelName}\0${serverRoutingId}`;
+        const current = this.clientServers.get(key);
+        if (current === undefined || current.connectionId !== connectionId)
+            return false;
+        if (current.descriptor.state !== 'disconnected') {
+            this.clientServers.set(key, {
+                descriptor: { ...current.descriptor, state: 'disconnected' },
+                connectionId
+            });
+            this.invalidateClientServerCandidates(channelName);
+        }
+        return true;
+    }
+    removeClientServer(channelName, serverRoutingId, connectionId) {
+        const removed = removeCurrent(this.clientServers, `${channelName}\0${serverRoutingId}`, connectionId);
+        if (removed)
+            this.invalidateClientServerCandidates(channelName);
+        return removed;
+    }
+    selectClientServer(channelName) {
+        return this.selectClientServerConnectionCore(channelName)?.descriptor;
+    }
+    selectClientServerConnection(channelName) {
+        return this.selectClientServerConnectionCore(channelName);
+    }
+    selectClientServerConnectionCore(channelName) {
+        let selection = this.clientServerSelections.get(channelName);
+        if (selection === undefined) {
+            selection = new service_weighted_selection_1.SmoothWeightedSelection(() => this.clientServerCandidates(channelName));
+            this.clientServerSelections.set(channelName, selection);
+        }
+        return selection.select();
+    }
+    clientServerDescriptors(channelName) {
+        return [...this.clientServers.values()]
+            .map(value => value.descriptor)
+            .filter(value => value.channelName === channelName)
+            .sort((left, right) => compareOrdinal(left.serverRoutingId, right.serverRoutingId))
+            .map(value => ({ ...value }));
+    }
+    admitFanoutPublisher(descriptor, connectionId) {
+        validateFanout(descriptor);
+        return this.admit(this.fanoutPublishers, `${descriptor.channelName}\0${descriptor.publisherRoutingId}`, descriptor, connectionId);
+    }
+    removeFanoutPublisher(channelName, publisherRoutingId, connectionId) {
+        return removeCurrent(this.fanoutPublishers, `${channelName}\0${publisherRoutingId}`, connectionId);
+    }
+    fanoutEndpoints(channelName) {
+        return [...this.fanoutPublishers.values()]
+            .map(value => value.descriptor)
+            .filter(value => value.channelName === channelName && value.state === 'serving')
+            .sort((left, right) => left.publisherRoutingId.localeCompare(right.publisherRoutingId))
+            .map(value => ({ ...value }));
+    }
+    admit(rows, key, descriptor, connectionId) {
+        requireText(connectionId, 'connectionId');
+        const current = rows.get(key);
+        if (current !== undefined
+            && current.descriptor.lifecycleGeneration === descriptor.lifecycleGeneration
+            && (current.descriptor.descriptorRevision > descriptor.descriptorRevision
+                || (current.descriptor.descriptorRevision === descriptor.descriptorRevision
+                    && !sameDescriptor(current.descriptor, descriptor)))) {
+            return false;
+        }
+        rows.set(key, { descriptor: { ...descriptor }, connectionId });
+        return true;
+    }
+    invalidateClientServerCandidates(channelName) {
+        if (this.clientServerSelections.has(channelName)) {
+            this.clientServerSelections.get(channelName).rebuild();
+        }
+    }
+    clientServerCandidates(channelName) {
+        return [...this.clientServers.values()]
+            .filter(value => value.descriptor.channelName === channelName
+            && value.descriptor.state === 'serving'
+            && value.descriptor.weight > 0)
+            .sort((left, right) => compareOrdinal(left.descriptor.serverRoutingId, right.descriptor.serverRoutingId))
+            .map(value => ({
+            id: value.descriptor.serverRoutingId,
+            weight: value.descriptor.weight,
+            value: Object.freeze({
+                descriptor: Object.freeze({ ...value.descriptor }),
+                connectionId: value.connectionId
+            })
+        }));
+    }
+}
+exports.ServiceDiscoveryRegistry = ServiceDiscoveryRegistry;
+function compareOrdinal(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function sameDescriptor(left, right) {
+    return JSON.stringify({
+        ...left,
+        lifecycleGeneration: left.lifecycleGeneration.toString(),
+        descriptorRevision: left.descriptorRevision.toString()
+    }) === JSON.stringify({
+        ...right,
+        lifecycleGeneration: right.lifecycleGeneration.toString(),
+        descriptorRevision: right.descriptorRevision.toString()
+    });
+}
+function sameClientServerDescriptorExceptState(left, right) {
+    return left.channelName === right.channelName
+        && left.serverRoutingId === right.serverRoutingId
+        && left.lifecycleGeneration === right.lifecycleGeneration
+        && left.descriptorRevision === right.descriptorRevision
+        && left.weight === right.weight
+        && left.securityIdentity === right.securityIdentity
+        && left.effectiveMaxMessageBytes === right.effectiveMaxMessageBytes
+        && left.advertisedEndpoint === right.advertisedEndpoint;
+}
+function removeCurrent(rows, key, connectionId) {
+    const current = rows.get(key);
+    if (current === undefined || current.connectionId !== connectionId)
+        return false;
+    rows.delete(key);
+    return true;
+}
+function validateClientServer(descriptor) {
+    requireText(descriptor.channelName, 'channelName');
+    requireText(descriptor.serverRoutingId, 'serverRoutingId');
+    requireText(descriptor.securityIdentity, 'securityIdentity');
+    requireText(descriptor.advertisedEndpoint, 'advertisedEndpoint');
+    validateRevision(descriptor.lifecycleGeneration, descriptor.descriptorRevision);
+    if (!Number.isInteger(descriptor.weight) || descriptor.weight < 0 || descriptor.weight > 10_000) {
+        throw new RangeError('ClientServer weight must be an integer in 0..10000.');
+    }
+    if (!Number.isSafeInteger(descriptor.effectiveMaxMessageBytes) || descriptor.effectiveMaxMessageBytes < 1) {
+        throw new RangeError('ClientServer message bound must be positive.');
+    }
+}
+function validateFanout(descriptor) {
+    requireText(descriptor.channelName, 'channelName');
+    requireText(descriptor.publisherRoutingId, 'publisherRoutingId');
+    requireText(descriptor.advertisedEndpoint, 'advertisedEndpoint');
+    validateRevision(descriptor.lifecycleGeneration, descriptor.descriptorRevision);
+}
+function validateRevision(lifecycle, revision) {
+    if (lifecycle <= 0n || revision <= 0n) {
+        throw new RangeError('Lifecycle generation and descriptor revision must be non-zero.');
+    }
+}
+function requireText(value, field) {
+    if (value.length === 0 || value.includes('\0')) {
+        throw new TypeError(`${field} must be non-empty text without NUL.`);
+    }
+}
+const service_weighted_selection_1 = require("./service-weighted-selection");

package/dist/runtime/foundation/service-instance-activation-recovery-codec.d.ts

@@ -0,0 +1,19 @@
+import type { ServiceInstanceActivationTarget } from './service-stateful-wire-codec';
+export interface ServiceInstanceActivationRecoveryEnvelope {
+    readonly target: ServiceInstanceActivationTarget;
+    readonly targetMeshName: string;
+    readonly sourceNodeRid: string;
+    readonly sourceNodeGeneration: bigint;
+    readonly sourceSpotId?: string;
+    readonly operationKind: 'send' | 'request';
+    readonly operation: {
+        readonly high: bigint;
+        readonly low: bigint;
+    };
+    readonly replyRouteId?: bigint;
+    readonly deadlineUnixMs: bigint;
+    readonly metadataFrame?: Uint8Array;
+    readonly applicationPayloadFrame: Uint8Array;
+}
+export declare function encodeInstanceActivationRecoveryEnvelope(value: ServiceInstanceActivationRecoveryEnvelope): Buffer;
+export declare function decodeInstanceActivationRecoveryEnvelope(encoded: Uint8Array): ServiceInstanceActivationRecoveryEnvelope;

package/dist/runtime/foundation/service-instance-activation-recovery-codec.js

@@ -0,0 +1,287 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeInstanceActivationRecoveryEnvelope = encodeInstanceActivationRecoveryEnvelope;
+exports.decodeInstanceActivationRecoveryEnvelope = decodeInstanceActivationRecoveryEnvelope;
+const service_relocation_runtime_1 = require("./service-relocation-runtime");
+const service_wire_m6a_codec_1 = require("./service-wire-m6a-codec");
+const service_metadata_codec_1 = require("./service-metadata-codec");
+const MAGIC = Buffer.from([0x5a, 0x4c, 0x49, 0x41]);
+const VERSION = 1;
+const FLAGS = 0;
+const MAX_ENCODED_BYTES = 1024 * 1024;
+const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true });
+function encodeInstanceActivationRecoveryEnvelope(value) {
+    requireOperation(value);
+    (0, service_wire_m6a_codec_1.validateApplicationPayloadFrame)(value.applicationPayloadFrame);
+    const targetSpotId = textBytes(value.target.targetSpotId, 'targetSpotId');
+    const stableType = textBytes(value.target.stableType, 'stableType');
+    const targetMeshName = textBytes(value.targetMeshName, 'targetMeshName');
+    const targetNodeRid = textBytes(value.target.targetNodeRid, 'targetNodeRid');
+    const descriptorVersion = textBytes(value.target.descriptorVersion, 'targetDescriptorVersion');
+    const sourceNodeRid = textBytes(value.sourceNodeRid, 'sourceNodeRid');
+    const sourceSpotId = value.sourceSpotId === undefined
+        ? undefined
+        : textBytes(value.sourceSpotId, 'sourceSpotId');
+    validatePositiveU64(value.target.targetNodeGeneration, 'targetNodeGeneration');
+    validatePositiveU64(value.sourceNodeGeneration, 'sourceNodeGeneration');
+    validateU64(value.operation.high, 'operation.high');
+    validateU64(value.operation.low, 'operation.low');
+    if (value.operationKind === 'request') {
+        validatePositiveU64(value.replyRouteId, 'replyRouteId');
+    }
+    validatePositiveU64(value.deadlineUnixMs, 'deadlineUnixMs');
+    const metadataFrame = value.metadataFrame === undefined
+        ? undefined
+        : (0, service_metadata_codec_1.validateServiceMetadataFrame)(value.metadataFrame);
+    const bodyLength = text8Size(targetSpotId)
+        + text8Size(stableType)
+        + text8Size(targetMeshName)
+        + text8Size(targetNodeRid)
+        + 8
+        + text8Size(descriptorVersion)
+        + text8Size(sourceNodeRid)
+        + 8
+        + 1 + (sourceSpotId === undefined ? 0 : text8Size(sourceSpotId))
+        + 1
+        + 8
+        + 8
+        + (value.operationKind === 'request' ? 8 : 0)
+        + 8
+        + 1 + (metadataFrame?.byteLength ?? 0)
+        + value.applicationPayloadFrame.byteLength;
+    const envelopeLength = 4 + 1 + 2 + 4 + bodyLength;
+    const encodedLength = envelopeLength + 4;
+    if (encodedLength > MAX_ENCODED_BYTES) {
+        throw new RangeError('Instance activation recovery envelope exceeds 1 MiB.');
+    }
+    const encoded = Buffer.allocUnsafe(encodedLength);
+    let offset = 0;
+    encoded.set(MAGIC, offset);
+    offset += MAGIC.byteLength;
+    encoded.writeUInt8(VERSION, offset);
+    offset += 1;
+    encoded.writeUInt16BE(FLAGS, offset);
+    offset += 2;
+    encoded.writeUInt32BE(bodyLength, offset);
+    offset += 4;
+    offset = writeText8(encoded, offset, targetSpotId);
+    offset = writeText8(encoded, offset, stableType);
+    offset = writeText8(encoded, offset, targetMeshName);
+    offset = writeText8(encoded, offset, targetNodeRid);
+    offset = writePositiveU64(encoded, offset, value.target.targetNodeGeneration);
+    offset = writeText8(encoded, offset, descriptorVersion);
+    offset = writeText8(encoded, offset, sourceNodeRid);
+    offset = writePositiveU64(encoded, offset, value.sourceNodeGeneration);
+    encoded.writeUInt8(sourceSpotId === undefined ? 0 : 1, offset);
+    offset += 1;
+    if (sourceSpotId !== undefined)
+        offset = writeText8(encoded, offset, sourceSpotId);
+    encoded.writeUInt8(value.operationKind === 'send' ? 1 : 2, offset);
+    offset += 1;
+    offset = writeU64(encoded, offset, value.operation.high);
+    offset = writeU64(encoded, offset, value.operation.low);
+    if (value.operationKind === 'request') {
+        offset = writePositiveU64(encoded, offset, value.replyRouteId);
+    }
+    offset = writePositiveU64(encoded, offset, value.deadlineUnixMs);
+    encoded.writeUInt8(metadataFrame === undefined ? 0 : 1, offset);
+    offset += 1;
+    if (metadataFrame !== undefined) {
+        encoded.set(metadataFrame, offset);
+        offset += metadataFrame.byteLength;
+    }
+    encoded.set(value.applicationPayloadFrame, offset);
+    offset += value.applicationPayloadFrame.byteLength;
+    if (offset !== envelopeLength) {
+        throw new Error('Instance activation recovery envelope length calculation is invalid.');
+    }
+    encoded.writeUInt32BE((0, service_relocation_runtime_1.crc32c)(encoded.subarray(0, envelopeLength)), envelopeLength);
+    return encoded;
+}
+function decodeInstanceActivationRecoveryEnvelope(encoded) {
+    if (encoded.byteLength > MAX_ENCODED_BYTES) {
+        throw new RangeError('Instance activation recovery envelope exceeds 1 MiB.');
+    }
+    const reader = new RecoveryReader(encoded);
+    reader.expect(MAGIC);
+    if (reader.u8() !== VERSION || reader.u16() !== FLAGS) {
+        throw new TypeError('Instance activation recovery envelope version or flags are invalid.');
+    }
+    const body = reader.takeReader(reader.u32());
+    const checksumOffset = reader.offset;
+    const checksum = reader.u32();
+    if (!reader.done || (0, service_relocation_runtime_1.crc32c)(reader.bytes.subarray(0, checksumOffset)) !== checksum) {
+        throw new TypeError('Instance activation recovery envelope checksum is invalid.');
+    }
+    const targetSpotId = body.text8();
+    const stableType = body.text8();
+    const targetMeshName = body.text8();
+    const targetNodeRid = body.text8();
+    const targetNodeGeneration = body.nonZeroU64();
+    const descriptorVersion = body.text8();
+    const sourceNodeRid = body.text8();
+    const sourceNodeGeneration = body.nonZeroU64();
+    const sourceSpotId = body.optionalText8();
+    const operationDiscriminator = body.u8();
+    if (operationDiscriminator !== 1 && operationDiscriminator !== 2) {
+        throw new TypeError('Instance activation recovery operation kind is invalid.');
+    }
+    const operation = { high: body.u64(), low: body.u64() };
+    if (operation.high === 0n && operation.low === 0n) {
+        throw new TypeError('Instance activation recovery operation identity is zero.');
+    }
+    const operationKind = operationDiscriminator === 1 ? 'send' : 'request';
+    const replyRouteId = operationKind === 'request' ? body.nonZeroU64() : undefined;
+    const deadlineUnixMs = body.nonZeroU64();
+    const hasMetadata = body.u8();
+    if (hasMetadata !== 0 && hasMetadata !== 1) {
+        throw new TypeError('Instance activation recovery metadata flag is invalid.');
+    }
+    const metadataFrame = hasMetadata === 1
+        ? body.metadataFrame()
+        : undefined;
+    const applicationPayloadFrame = body.takeRemaining();
+    (0, service_wire_m6a_codec_1.validateApplicationPayloadFrame)(applicationPayloadFrame);
+    if (!body.done) {
+        throw new TypeError('Instance activation recovery envelope has trailing bytes.');
+    }
+    return {
+        target: {
+            targetSpotId,
+            stableType,
+            targetNodeRid,
+            targetNodeGeneration,
+            descriptorVersion
+        },
+        targetMeshName,
+        sourceNodeRid,
+        sourceNodeGeneration,
+        ...(sourceSpotId === undefined ? {} : { sourceSpotId }),
+        operationKind,
+        operation,
+        ...(replyRouteId === undefined ? {} : { replyRouteId }),
+        deadlineUnixMs,
+        ...(metadataFrame === undefined ? {} : { metadataFrame }),
+        applicationPayloadFrame
+    };
+}
+function requireOperation(value) {
+    if (value.operation.high === 0n && value.operation.low === 0n) {
+        throw new TypeError('Instance activation recovery operation identity is zero.');
+    }
+    if (value.operationKind === 'request'
+        ? value.replyRouteId === undefined || value.replyRouteId <= 0n
+        : value.replyRouteId !== undefined) {
+        throw new TypeError('Instance activation recovery reply route does not match the operation.');
+    }
+}
+function textBytes(value, name) {
+    const bytes = Buffer.from(value, 'utf8');
+    if (bytes.byteLength < 1 || bytes.byteLength > 255 || bytes.includes(0)) {
+        throw new RangeError(`${name} must contain 1..255 UTF-8 bytes without NUL.`);
+    }
+    return bytes;
+}
+function text8Size(value) {
+    return 1 + value.byteLength;
+}
+function writeText8(target, offset, value) {
+    target.writeUInt8(value.byteLength, offset);
+    target.set(value, offset + 1);
+    return offset + 1 + value.byteLength;
+}
+function validatePositiveU64(value, name) {
+    if (value <= 0n || value > 0xffffffffffffffffn) {
+        throw new RangeError(`${name} is out of range.`);
+    }
+}
+function validateU64(value, name) {
+    if (value < 0n || value > 0xffffffffffffffffn) {
+        throw new RangeError(`${name} is out of range.`);
+    }
+}
+function writeU64(target, offset, value) {
+    target.writeBigUInt64BE(value, offset);
+    return offset + 8;
+}
+function writePositiveU64(target, offset, value) {
+    target.writeBigUInt64BE(value, offset);
+    return offset + 8;
+}
+class RecoveryReader {
+    bytes;
+    offset = 0;
+    constructor(value) {
+        this.bytes = Buffer.isBuffer(value)
+            ? value
+            : Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+    }
+    get done() {
+        return this.offset === this.bytes.byteLength;
+    }
+    expect(expected) {
+        const actual = this.take(expected.byteLength);
+        if (!actual.equals(expected)) {
+            throw new TypeError('Instance activation recovery envelope magic is invalid.');
+        }
+    }
+    u8() {
+        return this.take(1)[0];
+    }
+    u16() {
+        return this.take(2).readUInt16BE();
+    }
+    u32() {
+        return this.take(4).readUInt32BE();
+    }
+    u64() {
+        return this.take(8).readBigUInt64BE();
+    }
+    nonZeroU64() {
+        const value = this.u64();
+        if (value === 0n)
+            throw new TypeError('Instance activation recovery field is zero.');
+        return value;
+    }
+    text8() {
+        const bytes = this.take(this.u8());
+        if (bytes.byteLength === 0 || bytes.includes(0)) {
+            throw new TypeError('Instance activation recovery text is invalid.');
+        }
+        return FATAL_UTF8.decode(bytes);
+    }
+    optionalText8() {
+        const present = this.u8();
+        if (present === 0)
+            return undefined;
+        if (present !== 1)
+            throw new TypeError('Instance activation recovery optional flag is invalid.');
+        return this.text8();
+    }
+    metadataFrame() {
+        const start = this.offset;
+        if (this.u8() !== 1) {
+            throw new TypeError('Application metadata frame version is invalid.');
+        }
+        const count = this.u8();
+        for (let index = 0; index < count; index += 1) {
+            this.take(this.u8());
+            this.take(this.u16());
+        }
+        return (0, service_metadata_codec_1.validateServiceMetadataFrame)(this.bytes.subarray(start, this.offset));
+    }
+    takeRemaining() {
+        return this.take(this.bytes.byteLength - this.offset);
+    }
+    takeReader(length) {
+        return new RecoveryReader(this.take(length));
+    }
+    take(length) {
+        if (length < 0 || this.offset + length > this.bytes.byteLength) {
+            throw new TypeError('Instance activation recovery envelope is truncated.');
+        }
+        const value = this.bytes.subarray(this.offset, this.offset + length);
+        this.offset += length;
+        return value;
+    }
+}

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

@@ -0,0 +1,28 @@
+export interface ServiceProbe {
+    readonly nodeRoutingId: string;
+    readonly connectionId: string;
+    readonly probeId: bigint;
+}
+export interface ServiceLivenessTick {
+    readonly probes: readonly ServiceProbe[];
+    readonly timedOutNodes: readonly string[];
+}
+export declare const DEFAULT_SERVICE_PROBE_INTERVAL_MS = 5000;
+export declare const DEFAULT_SERVICE_PEER_TIMEOUT_MS = 15000;
+/** Uses monotonic milliseconds and never treats application traffic as a probe ACK. */
+export declare class ServiceLivenessRegistry {
+    private readonly probeIntervalMs;
+    private readonly peerTimeoutMs;
+    private readonly peers;
+    private nextProbeId;
+    constructor(probeIntervalMs?: number, peerTimeoutMs?: number);
+    admit(nodeRoutingId: string, connectionId: string, nowMs: number): void;
+    requestProbe(nodeRoutingId: string, connectionId: string, nowMs: number): boolean;
+    disconnect(nodeRoutingId: string, connectionId: string): boolean;
+    acknowledge(nodeRoutingId: string, connectionId: string, probeId: bigint, nowMs: number): boolean;
+    acknowledgeProbe(nodeRoutingId: string, connectionId: string, probeId: bigint): ServiceProbe | undefined;
+    tick(nowMs: number): ServiceLivenessTick;
+    get size(): number;
+    isReady(nodeRoutingId: string, connectionId: string): boolean;
+    private allocateProbeId;
+}

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

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceLivenessRegistry = exports.DEFAULT_SERVICE_PEER_TIMEOUT_MS = exports.DEFAULT_SERVICE_PROBE_INTERVAL_MS = void 0;
+exports.DEFAULT_SERVICE_PROBE_INTERVAL_MS = 5_000;
+exports.DEFAULT_SERVICE_PEER_TIMEOUT_MS = 15_000;
+/** Uses monotonic milliseconds and never treats application traffic as a probe ACK. */
+class ServiceLivenessRegistry {
+    probeIntervalMs;
+    peerTimeoutMs;
+    peers = new Map();
+    nextProbeId = 1n;
+    constructor(probeIntervalMs = exports.DEFAULT_SERVICE_PROBE_INTERVAL_MS, peerTimeoutMs = exports.DEFAULT_SERVICE_PEER_TIMEOUT_MS) {
+        this.probeIntervalMs = probeIntervalMs;
+        this.peerTimeoutMs = peerTimeoutMs;
+        if (!Number.isFinite(probeIntervalMs)
+            || probeIntervalMs <= 0
+            || !Number.isFinite(peerTimeoutMs)
+            || peerTimeoutMs <= probeIntervalMs) {
+            throw new RangeError('Liveness requires a positive probe interval and a larger timeout.');
+        }
+    }
+    admit(nodeRoutingId, connectionId, nowMs) {
+        requireIdentity(nodeRoutingId, 'nodeRoutingId');
+        requireIdentity(connectionId, 'connectionId');
+        const current = this.peers.get(nodeRoutingId);
+        if (current?.connectionId === connectionId)
+            return;
+        this.peers.set(nodeRoutingId, {
+            connectionId,
+            deadlineMs: nowMs + this.peerTimeoutMs,
+            nextProbeMs: nowMs + this.probeIntervalMs,
+            ready: false
+        });
+    }
+    requestProbe(nodeRoutingId, connectionId, nowMs) {
+        const current = this.peers.get(nodeRoutingId);
+        if (current === undefined
+            || current.connectionId !== connectionId
+            || current.ready
+            || current.outstandingProbe !== undefined)
+            return false;
+        current.nextProbeMs = Math.min(current.nextProbeMs, nowMs);
+        return true;
+    }
+    disconnect(nodeRoutingId, connectionId) {
+        const current = this.peers.get(nodeRoutingId);
+        if (current === undefined || current.connectionId !== connectionId)
+            return false;
+        this.peers.delete(nodeRoutingId);
+        return true;
+    }
+    acknowledge(nodeRoutingId, connectionId, probeId, nowMs) {
+        const current = this.peers.get(nodeRoutingId);
+        if (current === undefined
+            || current.connectionId !== connectionId
+            || current.outstandingProbe !== probeId) {
+            return false;
+        }
+        current.outstandingProbe = undefined;
+        current.deadlineMs = nowMs + this.peerTimeoutMs;
+        current.ready = true;
+        return true;
+    }
+    acknowledgeProbe(nodeRoutingId, connectionId, probeId) {
+        const current = this.peers.get(nodeRoutingId);
+        if (probeId <= 0n || current === undefined || current.connectionId !== connectionId) {
+            return undefined;
+        }
+        return { nodeRoutingId, connectionId, probeId };
+    }
+    tick(nowMs) {
+        const probes = [];
+        const timedOutNodes = [];
+        for (const [nodeRoutingId, peer] of this.peers) {
+            if (peer.deadlineMs <= nowMs) {
+                timedOutNodes.push(nodeRoutingId);
+                this.peers.delete(nodeRoutingId);
+                continue;
+            }
+            if (peer.nextProbeMs > nowMs)
+                continue;
+            peer.outstandingProbe ??= this.allocateProbeId();
+            probes.push({ nodeRoutingId, connectionId: peer.connectionId, probeId: peer.outstandingProbe });
+            do {
+                peer.nextProbeMs += this.probeIntervalMs;
+            } while (peer.nextProbeMs <= nowMs);
+        }
+        timedOutNodes.sort();
+        return { probes, timedOutNodes };
+    }
+    get size() {
+        return this.peers.size;
+    }
+    isReady(nodeRoutingId, connectionId) {
+        const current = this.peers.get(nodeRoutingId);
+        return current?.connectionId === connectionId && current.ready;
+    }
+    allocateProbeId() {
+        const result = this.nextProbeId++;
+        if (this.nextProbeId > 0xffffffffffffffffn)
+            this.nextProbeId = 1n;
+        return result;
+    }
+}
+exports.ServiceLivenessRegistry = ServiceLivenessRegistry;
+function requireIdentity(value, field) {
+    if (value.length === 0)
+        throw new TypeError(`${field} must be non-empty.`);
+}

package/dist/runtime/foundation/service-mailbox.d.ts

@@ -0,0 +1,60 @@
+import type { ApplicationJobRecordLease } from '../application-jobs/application-ingress-record-owner';
+export type ServiceMailboxDomain = 'application' | 'infrastructure';
+export interface ServiceMailboxRecord {
+    readonly owner: string;
+    readonly domain: ServiceMailboxDomain;
+    parts: readonly Uint8Array[];
+    readonly sourceRoutingId?: string;
+    readonly sourceRoute?: Uint8Array;
+    readonly requestSequence?: bigint;
+    readonly reply?: (parts: readonly Uint8Array[]) => void;
+    readonly correlation?: bigint;
+    readonly localReply?: (terminalResult: number, failureCode: number, payload?: {
+        readonly packetName: string;
+        readonly contentType: string;
+        readonly payload: Uint8Array;
+    }) => void;
+    readonly stateful?: unknown;
+    /** Host queue permit plus its ordinary Framework-owned ingress record. */
+    readonly applicationJob?: ApplicationJobRecordLease;
+}
+export interface ServiceMailboxClaim {
+    readonly owner: string;
+    readonly domain: ServiceMailboxDomain;
+    readonly serial: bigint;
+    readonly records: readonly ServiceMailboxRecord[];
+}
+export interface ServiceMailboxRelocationSeal {
+    readonly owner: string;
+    readonly serial: bigint;
+    readonly captured: readonly ServiceMailboxRecord[];
+}
+export interface ServiceMailboxLimits {
+    readonly applicationMessages: number;
+    readonly applicationBytes: number;
+    readonly infrastructureMessages: number;
+    readonly infrastructureBytes: number;
+}
+/** Level-triggered queues with one active application claim per owner. */
+export declare class ServiceMailbox {
+    private readonly onReady?;
+    private readonly application;
+    private readonly infrastructure;
+    private readonly relocationSeals;
+    private readonly relocatedOwners;
+    private nextClaimSerial;
+    private nextRelocationSerial;
+    private closed;
+    constructor(_legacyLimits?: ServiceMailboxLimits, onReady?: ((domain: ServiceMailboxDomain) => void) | undefined);
+    releaseClaimedPayload(record: ServiceMailboxRecord): void;
+    tryEnqueue(record: ServiceMailboxRecord): boolean;
+    tryClaim(domain: ServiceMailboxDomain, messageBudget: number, byteBudget: number): ServiceMailboxClaim | undefined;
+    release(claim: ServiceMailboxClaim, remaining?: readonly ServiceMailboxRecord[]): boolean;
+    trySealApplicationOwner(owner: string): ServiceMailboxRelocationSeal | undefined;
+    abortRelocation(seal: ServiceMailboxRelocationSeal): boolean;
+    commitRelocation(seal: ServiceMailboxRelocationSeal): readonly ServiceMailboxRecord[] | undefined;
+    close(): void;
+    pendingMessages(domain: ServiceMailboxDomain): number;
+    pendingBytes(domain: ServiceMailboxDomain): number;
+    private domain;
+}