@zlink-systems/framework 0.29.1 → 0.30.1

package/dist/runtime/foundation/service-stateful-runtime.js

@@ -7,7 +7,7 @@ const node_async_hooks_1 = require("node:async_hooks");
 const contracts_1 = require("../../contracts");
 const service_authority_payload_codec_1 = require("./service-authority-payload-codec");
 const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
-const abort_1 = require("../abort");
+const durable_service_request_1 = require("./durable-service-request");
 const admission_1 = require("../admission");
 const runtime_values_1 = require("../backend/runtime-values");
 const message_flow_1 = require("../diagnostics/message-flow");
@@ -25,7 +25,6 @@ const service_stateful_wire_codec_1 = require("./service-stateful-wire-codec");
 const service_wire_binary_primitives_1 = require("./service-wire-binary-primitives");
 const service_wire_constants_generated_1 = require("./service-wire-constants.generated");
 const service_wire_m6a_codec_1 = require("./service-wire-m6a-codec");
-const STATEFUL_OPERATION_RETRY_TICK_MS = 20;
 const MAX_NODE_TIMER_DELAY_MS = 2_147_483_647;
 const SPOT_MOVING = 34;
 const USER_SPOT_OPERATION_CAPACITY = 65_536;
@@ -92,7 +91,7 @@ class ServiceStatefulRuntime {
         this.operations = new service_stateful_registry_1.ServiceTerminalOperationRegistry(new operation_registry_1.OperationRegistry(undefined, onPendingOperationsChanged));
         this.registry = new service_stateful_registry_1.ServiceStatefulRegistry(nodeRid, nodeGeneration);
         this.registry.createEntrySpot(nodeRid);
-        raw.setServiceIngress((record) => this.ingress(record));
+        raw.setServiceIngress((record) => this.ingress(record), acceptsStatefulIngress);
     }
     setMailboxDropHandler(handler) {
         this.mailboxDropHandler = handler;
@@ -345,7 +344,7 @@ class ServiceStatefulRuntime {
         const record = {
             kind: 'instanceSpot',
             activation: 'missing',
-            target,
+            target: { ...target, targetMeshName: envelope.targetMeshName },
             sourceNodeGeneration: envelope.sourceNodeGeneration,
             sourceNodeRid: envelope.sourceNodeRid,
             ...(envelope.sourceSpotId === undefined ? {} : { sourceSpotId: envelope.sourceSpotId }),
@@ -362,7 +361,7 @@ class ServiceStatefulRuntime {
                 flags: envelope.metadataFrame === undefined ? 0 : service_stateful_wire_codec_1.M6bServiceWireFlag.metadata,
                 sourceRoutingId: envelope.sourceNodeRid,
                 parts: [
-                    (0, service_stateful_wire_codec_1.encodeInstanceSpotActivationHeader)(target, envelope.sourceNodeGeneration, envelope.sourceNodeRid, envelope.sourceSpotId, envelope.operationKind, envelope.operation, envelope.deadlineUnixMs, envelope.replyRouteId, envelope.metadataFrame !== undefined)
+                    (0, service_stateful_wire_codec_1.encodeInstanceSpotActivationHeader)(record.target, envelope.sourceNodeGeneration, envelope.sourceNodeRid, envelope.sourceSpotId, envelope.operationKind, envelope.operation, envelope.deadlineUnixMs, envelope.replyRouteId, envelope.metadataFrame !== undefined)
                 ],
                 applicationJobOwner
             }, record, Buffer.from(envelope.applicationPayloadFrame), spot, undefined, terminal.onTerminalCompletion, envelope.metadataFrame === undefined
@@ -679,7 +678,7 @@ class ServiceStatefulRuntime {
         });
         return this.submitOneWay(target.targetNodeRid, [header, (0, service_wire_m6a_codec_1.encodeApplicationPayload)(payload)]);
     }
-    requestToSpot(sourceSpotId, requested, payload, timeoutMs) {
+    requestToSpot(sourceSpotId, requested, payload, timeoutMs, onAdmitted) {
         const pending = this.operations.register(timeoutMs);
         const target = this.acceptSpotAuthority(requested);
         if (target === undefined) {
@@ -690,7 +689,7 @@ class ServiceStatefulRuntime {
             high: this.nodeGeneration,
             low: this.nextMessageFollowOperation++
         });
-        this.submitRequest(pending, target.targetNodeRid, [header, (0, service_wire_m6a_codec_1.encodeApplicationPayload)(payload)], timeoutMs, 'spotRequest');
+        this.submitRequest(pending, target.targetNodeRid, [header, (0, service_wire_m6a_codec_1.encodeApplicationPayload)(payload)], timeoutMs, 'spotRequest', undefined, onAdmitted);
         return pending;
     }
     async sendToActor(target, _targetNodeGeneration, _authorityOwnerGeneration, payload, sourceActor, boundSession) {
@@ -705,7 +704,7 @@ class ServiceStatefulRuntime {
             }, { high: this.nodeGeneration, low: this.nextMessageFollowOperation++ });
         return this.submitOneWay(target.nodeRid, [header, (0, service_wire_m6a_codec_1.encodeApplicationPayload)(payload)]);
     }
-    requestToActor(target, _targetNodeGeneration, _authorityOwnerGeneration, payload, timeoutMs, sourceActor, boundSession) {
+    requestToActor(target, _targetNodeGeneration, _authorityOwnerGeneration, payload, timeoutMs, sourceActor, boundSession, onAdmitted) {
         const pending = this.operations.register(timeoutMs);
         const route = this.tryActorFence(target);
         if (route === undefined) {
@@ -718,7 +717,7 @@ class ServiceStatefulRuntime {
                 ...boundSession,
                 sequence: this.nextSessionSequence++
             }, { high: this.nodeGeneration, low: this.nextMessageFollowOperation++ });
-        this.submitRequest(pending, target.nodeRid, [header, (0, service_wire_m6a_codec_1.encodeApplicationPayload)(payload)], timeoutMs, 'actorRequest');
+        this.submitRequest(pending, target.nodeRid, [header, (0, service_wire_m6a_codec_1.encodeApplicationPayload)(payload)], timeoutMs, 'actorRequest', undefined, onAdmitted);
         return pending;
     }
     async sendToInstanceSpot(route, payload, sourceSpotId, metadataFrame, instanceIntent = false) {
@@ -737,12 +736,12 @@ class ServiceStatefulRuntime {
             payloadFrame
         ], metadataFrame));
     }
-    requestToInstanceSpot(route, payload, timeoutMs, sourceSpotId, metadataFrame, instanceIntent = false) {
+    requestToInstanceSpot(route, payload, timeoutMs, sourceSpotId, metadataFrame, instanceIntent = false, onAdmitted) {
         const pending = this.operations.register(timeoutMs);
         this.submitRequest(pending, route.targetNodeRid, instanceOperationParts([
             (0, service_stateful_wire_codec_1.encodeInstanceSpotHeader)(route, this.nodeGeneration, this.nodeRid, sourceSpotId, 'request', { high: operation_identity_1.ZLINK_NATIVE_CORRELATION_OPERATION_NAMESPACE, low: pending.id }, pending.id, metadataFrame !== undefined, instanceIntent),
             (0, service_wire_m6a_codec_1.encodeApplicationPayload)(payload)
-        ], metadataFrame), timeoutMs, 'instanceSpotRequest');
+        ], metadataFrame), timeoutMs, 'instanceSpotRequest', undefined, onAdmitted);
         return pending;
     }
     requestToMissingInstanceSpot(target, payload, timeoutMs, sourceSpotId, metadataFrame) {
@@ -750,13 +749,13 @@ class ServiceStatefulRuntime {
         const payloadFrame = (0, service_wire_m6a_codec_1.encodeApplicationPayload)(payload);
         return this.requestToMissingInstanceSpotFrame(target, payloadFrame, deadlineUnixMs, sourceSpotId, metadataFrame);
     }
-    requestToMissingInstanceSpotFrame(target, payloadFrame, deadlineUnixMs, sourceSpotId, metadataFrame) {
+    requestToMissingInstanceSpotFrame(target, payloadFrame, deadlineUnixMs, sourceSpotId, metadataFrame, onAdmitted) {
         const timeoutMs = remainingDeadlineMs(deadlineUnixMs);
         const pending = this.operations.register(timeoutMs);
         this.submitRequest(pending, target.targetNodeRid, instanceOperationParts([
             (0, service_stateful_wire_codec_1.encodeInstanceSpotActivationHeader)(target, this.nodeGeneration, this.nodeRid, sourceSpotId, 'request', { high: operation_identity_1.ZLINK_NATIVE_CORRELATION_OPERATION_NAMESPACE, low: pending.id }, deadlineUnixMs, pending.id, metadataFrame !== undefined),
             payloadFrame
-        ], metadataFrame), timeoutMs, 'instanceSpotRequest');
+        ], metadataFrame), timeoutMs, 'instanceSpotRequest', undefined, onAdmitted);
         return pending;
     }
     lookupRemoteActor(targetNodeRid, actorId, timeoutMs) {
@@ -1072,25 +1071,6 @@ class ServiceStatefulRuntime {
         this.spotMessageFollow.clear();
     }
     async ingress(record) {
-        // These frozen relocation controls overlap the legacy stateful command
-        // number range (30-34). They are bare infrastructure records and must
-        // fall through to RawServiceMeshRuntime's relocation ingress instead of
-        // being decoded as stateful actor/spot work.
-        if (record.command === service_stateful_wire_codec_1.M6bServiceWireCommand.relocationReady ||
-            record.command === service_stateful_wire_codec_1.M6bServiceWireCommand.relocationData ||
-            record.command === service_stateful_wire_codec_1.M6bServiceWireCommand.replyRelay ||
-            record.command === service_stateful_wire_codec_1.M6bServiceWireCommand.relocationCutover) {
-            return undefined;
-        }
-        if (record.command < service_stateful_wire_codec_1.M6bServiceWireCommand.spotSend ||
-            (record.command > service_stateful_wire_codec_1.M6bServiceWireCommand.instanceSpot &&
-                record.command !== service_stateful_wire_codec_1.M6bServiceWireCommand.userSpotCreate &&
-                record.command !== service_stateful_wire_codec_1.M6bServiceWireCommand.userSpotClose &&
-                record.command !== service_stateful_wire_codec_1.M6bServiceWireCommand.actorCreate &&
-                record.command !== service_stateful_wire_codec_1.M6bServiceWireCommand.messageFollow &&
-                record.command !== service_stateful_wire_codec_1.M6bServiceWireCommand.boundSessionReplaced)) {
-            return undefined;
-        }
         let decoded;
         let canonicalActorJoin;
         try {
@@ -1329,12 +1309,14 @@ class ServiceStatefulRuntime {
         if (record.activation === 'missing' && this.asyncInstanceAuthority !== undefined) {
             const ownedIngress = shareIngressOwnership(ingress);
             void this.continueMissingInstanceActivation(ownedIngress, record, payloadFrame, localReply, metadataFrame).finally(() => ownedIngress.applicationJobOwner?.close());
+            ingress.onAdmitted?.();
             return 'infrastructure';
         }
         if (record.activation === 'ready' &&
             this.needsInstanceApplicationMaterialization(ingress, record)) {
             const ownedIngress = shareIngressOwnership(ingress);
             void this.continueReadyInstanceMaterialization(ownedIngress, record, payloadFrame, metadataFrame).finally(() => ownedIngress.applicationJobOwner?.close());
+            ingress.onAdmitted?.();
             return 'infrastructure';
         }
         const spot = this.requireInstanceActivation(ingress, record);
@@ -1739,6 +1721,18 @@ class ServiceStatefulRuntime {
         }
         return activation.spot;
     }
+    localReadyInstance(target, route) {
+        const local = this.registry.spot(target.targetSpotId);
+        if (local !== undefined &&
+            (local.kind !== 'instance' || local.stableType !== target.stableType)) {
+            throw new service_stateful_registry_1.ServiceStaleGenerationError('spot', target.targetSpotId);
+        }
+        return local !== undefined &&
+            local.state === 'ready' &&
+            routeMatchesLocal(route, local, this.nodeRid, this.nodeGeneration)
+            ? local
+            : undefined;
+    }
     activateMissingInstanceAsync(record, payloadFrame, metadataFrame, admit) {
         const key = record.target.targetSpotId;
         const pending = this.pendingInstanceActivations.get(key);
@@ -1747,7 +1741,15 @@ class ServiceStatefulRuntime {
                 ...activation,
                 stableType: record.target.stableType
             }));
-        const operation = ready.then((value) => {
+        const operation = ready.then(async (value) => {
+            if (pending !== undefined) {
+                await this.asyncInstanceAuthority?.read(record.target, undefined, {
+                    ...record,
+                    targetMeshName: record.target.targetMeshName,
+                    ...(metadataFrame === undefined ? {} : { metadataFrame }),
+                    applicationPayloadFrame: payloadFrame
+                }, (route) => this.localReadyInstance(record.target, route) !== undefined);
+            }
             if (value.stableType !== record.target.stableType) {
                 throw new contracts_1.ZLinkFrameworkException(contracts_1.ZLinkFrameworkErrorKind.TypeMismatch, 'Instance Spot type does not match.');
             }
@@ -1776,8 +1778,14 @@ class ServiceStatefulRuntime {
         if (authority === undefined) {
             throw new Error('Async Instance activation authority is not registered.');
         }
+        const activationRequest = {
+            ...record,
+            targetMeshName: record.target.targetMeshName,
+            ...(metadataFrame === undefined ? {} : { metadataFrame }),
+            applicationPayloadFrame: payloadFrame
+        };
+        const current = await authority.read(target, true, activationRequest, (route) => this.localReadyInstance(target, route) !== undefined);
         const local = this.registry.spot(target.targetSpotId);
-        const current = await authority.read(target);
         if (current.kind === 'creating' &&
             current.authority?.allocation.state === 'active' &&
             this.instanceApplicationLifecycle?.isMaterializing?.(target) === true) {
@@ -1821,13 +1829,9 @@ class ServiceStatefulRuntime {
             if (current.route.targetNodeGeneration !== this.nodeGeneration) {
                 throw new service_stateful_registry_1.ServiceStaleGenerationError('spot', target.targetSpotId);
             }
-            if (local !== undefined &&
-                (local.kind !== 'instance' || local.stableType !== target.stableType)) {
-                throw new service_stateful_registry_1.ServiceStaleGenerationError('spot', target.targetSpotId);
-            }
-            if (local !== undefined &&
-                routeMatchesLocal(current.route, local, this.nodeRid, this.nodeGeneration)) {
-                return { spot: local, route: current.route };
+            const readyLocal = this.localReadyInstance(target, current.route);
+            if (readyLocal !== undefined) {
+                return { spot: readyLocal, route: current.route };
             }
             return await this.reconcileReadyInstanceProjection(target, current.route, authority);
         }
@@ -1864,18 +1868,7 @@ class ServiceStatefulRuntime {
         const deadline = operationDeadline(record.deadlineUnixMs);
         let reserved;
         try {
-            reserved = await authority.reserve({
-                target,
-                sourceNodeRid: record.sourceNodeRid,
-                sourceNodeGeneration: record.sourceNodeGeneration,
-                ...(record.sourceSpotId === undefined ? {} : { sourceSpotId: record.sourceSpotId }),
-                operationKind: record.operationKind,
-                operation: record.operation,
-                ...(record.replyRouteId === undefined ? {} : { replyRouteId: record.replyRouteId }),
-                deadlineUnixMs: record.deadlineUnixMs,
-                ...(metadataFrame === undefined ? {} : { metadataFrame }),
-                applicationPayloadFrame: payloadFrame
-            }, deadline.signal);
+            reserved = await authority.reserve(activationRequest, deadline.signal);
         }
         finally {
             deadline.close();
@@ -2369,8 +2362,10 @@ class ServiceStatefulRuntime {
             stateful,
             applicationJob
         });
-        if (accepted)
+        if (accepted) {
+            ingress.onAdmitted?.();
             return domain;
+        }
         applicationJob.close();
         if (stateful.reply !== undefined) {
             const result = failure((0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotMoving, `Mailbox owner '${owner}' no longer accepts work on this runtime.`));
@@ -2671,57 +2666,11 @@ class ServiceStatefulRuntime {
         }
     }
     async requestDurableOperation(targetNodeRid, parts, correlation, operationKind, deadlineMs) {
-        const stop = new AbortController();
-        const unobserve = this.raw.observePeerConnectionIntentRemoved((nodeRoutingId) => {
-            if (nodeRoutingId === targetNodeRid) {
-                stop.abort((0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, `${operationKind} target node lifecycle ended.`, true));
-            }
-        });
-        let wasAdmitted = false;
-        try {
-            // Only durable lifecycle operations replay these frozen frames. Received
-            // envelopes leave this loop before decoding, including failure terminals.
-            for (;;) {
-                this.requireOpen();
-                stop.signal.throwIfAborted();
-                const remainingMs = Math.ceil(deadlineMs - performance.now());
-                if (remainingMs <= 0)
-                    throw durableOperationExhausted(operationKind, wasAdmitted);
-                try {
-                    return await (0, abort_1.awaitWithAbort)(targetNodeRid === this.nodeRid
-                        ? this.requestLocalInfrastructure(parts[0], correlation, remainingMs)
-                        : this.raw.requestService(targetNodeRid, parts, remainingMs), stop.signal);
-                }
-                catch (error) {
-                    stop.signal.throwIfAborted();
-                    if (!durableRequestCanReplay(error))
-                        throw error;
-                    if (durableRequestWasAdmitted(error))
-                        wasAdmitted = true;
-                    const retryDelayMs = Math.min(STATEFUL_OPERATION_RETRY_TICK_MS, deadlineMs - performance.now());
-                    if (retryDelayMs <= 0) {
-                        throw durableOperationExhausted(operationKind, wasAdmitted, error);
-                    }
-                    let timer;
-                    try {
-                        await (0, abort_1.awaitWithAbort)(new Promise((resolve) => {
-                            timer = setTimeout(resolve, retryDelayMs);
-                        }), stop.signal);
-                    }
-                    finally {
-                        if (timer !== undefined)
-                            clearTimeout(timer);
-                    }
-                }
-            }
-        }
-        catch (error) {
-            stop.signal.throwIfAborted();
-            throw error;
-        }
-        finally {
-            unobserve();
+        this.requireOpen();
+        if (targetNodeRid === this.nodeRid) {
+            return this.requestLocalInfrastructure(parts[0], correlation, Math.ceil(deadlineMs - performance.now()));
         }
+        return (0, durable_service_request_1.requestDurableService)(this.raw, targetNodeRid, parts, deadlineMs, operationKind);
     }
     requestLocalInfrastructure(header, requestSequence, timeoutMs) {
         return new Promise((resolve, reject) => {
@@ -2827,7 +2776,7 @@ class ServiceStatefulRuntime {
             ? runtime_values_1.SubmitResult.Ok
             : runtime_values_1.SubmitResult.NotConnected;
     }
-    submitRequest(pending, targetNodeRid, parts, timeoutMs, operationKind, actor) {
+    submitRequest(pending, targetNodeRid, parts, timeoutMs, operationKind, actor, onAdmitted) {
         if (targetNodeRid === this.nodeRid) {
             const deadlineUnixMs = BigInt(Date.now() + Math.max(0, timeoutMs));
             const capacityStop = new AbortController();
@@ -2842,6 +2791,7 @@ class ServiceStatefulRuntime {
                         flags: parts[0][service_wire_binary_primitives_1.SERVICE_WIRE_FLAGS_OFFSET],
                         sourceRoutingId: this.nodeRid,
                         requestSequence: pending.id,
+                        onAdmitted,
                         parts,
                         applicationJobOwner
                     };
@@ -2856,7 +2806,7 @@ class ServiceStatefulRuntime {
             })().catch((error) => this.operations.reply(pending.id, failure(error)));
             return;
         }
-        void this.raw.requestService(targetNodeRid, parts, timeoutMs).then((reply) => this.completeRemoteReply(pending, targetNodeRid, operationKind, actor, reply), (error) => this.operations.fail(pending.id, error));
+        void this.raw.requestService(targetNodeRid, parts, timeoutMs, onAdmitted).then((reply) => this.completeRemoteReply(pending, targetNodeRid, operationKind, actor, reply), (error) => this.operations.fail(pending.id, error));
     }
     submitActorJoin(pending, actor, targetNodeRid, target, payload, deadlineMs, canonical) {
         const actorRoute = canonical === undefined
@@ -3587,26 +3537,6 @@ function operationDeadline(deadlineUnixMs) {
 function operationReplayExpired(replayExpiresAtMs) {
     return performance.now() > replayExpiresAtMs;
 }
-function durableRequestWasAdmitted(error) {
-    // Request NotConnected includes Core handover of an admitted request. The
-    // submit/request phase, rather than the result number, owns this distinction.
-    return (0, runtime_values_1.isZLinkBackendResultError)(error) && error.operation === 'request';
-}
-function durableOperationExhausted(operationKind, wasAdmitted, cause) {
-    return (0, framework_errors_internal_1.createInternalFrameworkException)(wasAdmitted
-        ? framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded
-        : framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, `${operationKind} exhausted its end-to-end deadline.`, true, cause);
-}
-function durableRequestCanReplay(error) {
-    if (!(0, runtime_values_1.isZLinkBackendResultError)(error))
-        return false;
-    return error.operation === 'request'
-        ? error.result === runtime_values_1.RequestResult.NotConnected || error.result === runtime_values_1.RequestResult.TimedOut
-        : error.result === runtime_values_1.SubmitResult.NotConnected ||
-            error.result === runtime_values_1.SubmitResult.NotFound ||
-            error.result === runtime_values_1.SubmitResult.NotAdmitted ||
-            error.result === runtime_values_1.SubmitResult.Backpressured;
-}
 function remainingDeadlineMs(deadlineUnixMs) {
     const remainingMs = deadlineUnixMs - BigInt(Date.now());
     if (remainingMs <= 0n) {
@@ -3933,3 +3863,25 @@ function instanceOperationParts(headerAndPayload, metadataFrame) {
 function statefulMailboxData(record) {
     return record.stateful;
 }
+function acceptsStatefulIngress(command) {
+    // These frozen relocation controls overlap the legacy stateful command
+    // number range (30-34). They are bare infrastructure records and must
+    // fall through to RawServiceMeshRuntime's relocation ingress instead of
+    // being decoded as stateful actor/spot work.
+    if (command === service_stateful_wire_codec_1.M6bServiceWireCommand.relocationReady ||
+        command === service_stateful_wire_codec_1.M6bServiceWireCommand.relocationData ||
+        command === service_stateful_wire_codec_1.M6bServiceWireCommand.replyRelay ||
+        command === service_stateful_wire_codec_1.M6bServiceWireCommand.relocationCutover) {
+        return false;
+    }
+    if (command < service_stateful_wire_codec_1.M6bServiceWireCommand.spotSend ||
+        (command > service_stateful_wire_codec_1.M6bServiceWireCommand.instanceSpot &&
+            command !== service_stateful_wire_codec_1.M6bServiceWireCommand.userSpotCreate &&
+            command !== service_stateful_wire_codec_1.M6bServiceWireCommand.userSpotClose &&
+            command !== service_stateful_wire_codec_1.M6bServiceWireCommand.actorCreate &&
+            command !== service_stateful_wire_codec_1.M6bServiceWireCommand.messageFollow &&
+            command !== service_stateful_wire_codec_1.M6bServiceWireCommand.boundSessionReplaced)) {
+        return false;
+    }
+    return true;
+}

package/dist/runtime/foundation/service-stateful-wire-codec.d.ts

@@ -126,11 +126,6 @@ export interface ServiceMaintenanceRelocationPrepare extends ServiceWireRelocati
     /** CRC-32C (Castagnoli) over the fully assembled payload bytes. */
     readonly payloadChecksumCrc32c: number;
     readonly applicationVersion: bigint;
-    /** NODE-INTERNAL; serialized as extra frames after canonical command 40. */
-    readonly nodeInternalBoundSessions?: readonly {
-        readonly participantKey: string;
-        readonly payload: Uint8Array;
-    }[];
 }
 export interface ServiceMaintenanceRelocationReady extends ServiceWireRelocationBase {
     readonly kind: 'ready';
@@ -320,6 +315,9 @@ export interface ServiceInstanceActivationTarget {
     readonly stableType: string;
     readonly descriptorVersion: string;
 }
+export interface ServiceInstanceColdActivationTarget extends ServiceInstanceActivationTarget {
+    readonly targetMeshName: string;
+}
 export interface ServiceUserSpotReservationFence {
     readonly reservationId: string;
     readonly expectedStoreVersion: string;
@@ -475,7 +473,7 @@ export type ServiceStatefulWireRecord = {
 } | {
     readonly kind: 'instanceSpot';
     readonly activation: 'missing';
-    readonly target: ServiceInstanceActivationTarget;
+    readonly target: ServiceInstanceColdActivationTarget;
     readonly sourceNodeGeneration: bigint;
     readonly sourceNodeRid: string;
     readonly sourceSpotId?: string;
@@ -549,7 +547,7 @@ export declare function encodeInstanceSpotHeader(route: ServiceInstanceRouteFenc
     readonly high: bigint;
     readonly low: bigint;
 }, replyRouteId?: bigint, hasMetadata?: boolean, instanceIntent?: boolean): Buffer;
-export declare function encodeInstanceSpotActivationHeader(target: ServiceInstanceActivationTarget, sourceNodeGeneration: bigint, sourceNodeRid: string, sourceSpotId: string | undefined, operationKind: 'send' | 'request', operation: {
+export declare function encodeInstanceSpotActivationHeader(target: ServiceInstanceColdActivationTarget, sourceNodeGeneration: bigint, sourceNodeRid: string, sourceSpotId: string | undefined, operationKind: 'send' | 'request', operation: {
     readonly high: bigint;
     readonly low: bigint;
 }, deadlineUnixMs: bigint, replyRouteId?: bigint, hasMetadata?: boolean): Buffer;

package/dist/runtime/foundation/service-stateful-wire-codec.js

@@ -47,8 +47,6 @@ const service_wire_constants_generated_1 = require("./service-wire-constants.gen
 const service_wire_m6a_codec_1 = require("./service-wire-m6a-codec");
 const MESSAGE_FOLLOW_MAX_BODY_BYTES = 16 * 1024 * 1024;
 const MESSAGE_FOLLOW_VERSION = 1;
-const INSTANCE_ROUTE_VERSION = 1;
-const INSTANCE_ACTIVATION_VERSION = 2;
 const PREFIX_SIZE = service_wire_binary_primitives_1.SERVICE_WIRE_PREFIX_SIZE;
 const MAGIC_0 = service_wire_constants_generated_1.SERVICE_WIRE_MAGIC[0];
 const MAGIC_1 = service_wire_constants_generated_1.SERVICE_WIRE_MAGIC[1];
@@ -653,8 +651,17 @@ function encodeInstanceSpotActivationHeader(target, sourceNodeGeneration, source
     if (operationKind === 'send' && replyRouteId !== undefined) {
         throw new RangeError('Instance Spot send must not carry a reply route.');
     }
-    const targetBody = concat(rid(target.targetNodeRid, 'targetNodeRid'), u64(target.targetNodeGeneration), rid(target.targetSpotId, 'targetSpotId'), text16(target.stableType, 'stableType'), text16(target.descriptorVersion, 'descriptorVersion'));
-    return concat(prefix(exports.M6bServiceWireCommand.instanceSpot, hasMetadata ? exports.M6bServiceWireFlag.metadata : 0), Buffer.of(INSTANCE_ACTIVATION_VERSION), u16(targetBody.byteLength), targetBody, u64Any(sourceNodeGeneration), rid(sourceNodeRid, 'sourceNodeRid'), optionalRid(sourceSpotId), Buffer.of(operationKind === 'send' ? 1 : 2), u64Any(operation.high), u64Any(operation.low), u64(deadlineUnixMs), ...(operationKind === 'request' ? [u64(requirePositive(replyRouteId, 'replyRouteId'))] : []));
+    const encodedRoute = (0, service_wire_codec_generated_1.encodeInstanceRouteV1)({
+        routeKind: 'coldActivation',
+        targetNodeRid: toGeneratedRoutingId(target.targetNodeRid, 'targetNodeRid'),
+        targetNodeGeneration: target.targetNodeGeneration,
+        targetSpotId: target.targetSpotId,
+        targetMeshName: target.targetMeshName,
+        stableType: target.stableType,
+        targetDescriptorVersion: target.descriptorVersion,
+        deadlineUnixMs
+    }, STATEFUL_MESSAGE_CONTEXT);
+    return concat(prefix(exports.M6bServiceWireCommand.instanceSpot, hasMetadata ? exports.M6bServiceWireFlag.metadata : 0), encodedRoute, u64Any(sourceNodeGeneration), rid(sourceNodeRid, 'sourceNodeRid'), optionalRid(sourceSpotId), Buffer.of(operationKind === 'send' ? 1 : 2), u64Any(operation.high), u64Any(operation.low), ...(operationKind === 'request' ? [u64(requirePositive(replyRouteId, 'replyRouteId'))] : []));
 }
 function encodeUserSpotCreateHeader(record) {
     return Buffer.from((0, service_wire_pilot_codec_generated_1.encodeUserSpotCreate47)(toGeneratedUserSpotCreate(record)));
@@ -878,45 +885,27 @@ function decodeStatefulHeader(frame, payloadFrame, metadataFrame) {
                 fail(`Invalid command flags '${command.flags}'.`);
             }
             const routeStart = reader.offset;
-            const version = reader.u8('instanceRoute.version');
-            if (version !== INSTANCE_ROUTE_VERSION && version !== INSTANCE_ACTIVATION_VERSION)
-                fail('Unsupported Instance route version.');
+            reader.u8('instanceRoute.kind');
             const routeLength = reader.u16('instanceRoute.length');
             const routeEnd = reader.offset + routeLength;
-            const generatedReadyRoute = version === INSTANCE_ROUTE_VERSION
-                ? (0, service_wire_codec_generated_1.decodeInstanceRouteV1)(reader.bytes.subarray(routeStart, routeEnd), STATEFUL_MESSAGE_CONTEXT)
-                : undefined;
-            if (generatedReadyRoute !== undefined && generatedReadyRoute.routeKind !== 'ready') {
-                fail('Invalid Ready Instance route kind.');
-            }
-            const commonTarget = generatedReadyRoute?.routeKind === 'ready'
-                ? {
-                    targetNodeRid: fromGeneratedRoutingId(generatedReadyRoute.targetNodeRid, 'targetNodeRid'),
-                    targetNodeGeneration: generatedReadyRoute.targetNodeGeneration,
-                    targetSpotId: generatedReadyRoute.targetSpotId
-                }
-                : {
-                    targetNodeRid: reader.rid('targetNodeRid'),
-                    targetNodeGeneration: reader.nonZeroU64('targetNodeGeneration'),
-                    targetSpotId: reader.rid('targetSpotId')
-                };
-            const route = generatedReadyRoute?.routeKind === 'ready'
-                ? {
-                    ...commonTarget,
-                    ...generatedReadyRoute.authority
-                }
+            const generatedRoute = decodeCanonicalInstanceRoute(reader.bytes.subarray(routeStart, routeEnd));
+            const commonTarget = {
+                targetNodeRid: fromGeneratedRoutingId(generatedRoute.targetNodeRid, 'targetNodeRid'),
+                targetNodeGeneration: generatedRoute.targetNodeGeneration,
+                targetSpotId: generatedRoute.targetSpotId
+            };
+            const route = generatedRoute.routeKind === 'ready'
+                ? { ...commonTarget, ...generatedRoute.authority }
                 : undefined;
-            const target = version === INSTANCE_ACTIVATION_VERSION
+            const target = generatedRoute.routeKind === 'coldActivation'
                 ? {
                     ...commonTarget,
-                    stableType: reader.text16('stableType'),
-                    descriptorVersion: reader.text16('descriptorVersion')
+                    targetMeshName: generatedRoute.targetMeshName,
+                    stableType: generatedRoute.stableType,
+                    descriptorVersion: generatedRoute.targetDescriptorVersion
                 }
                 : undefined;
-            if (generatedReadyRoute !== undefined)
-                reader.offset = routeEnd;
-            if (reader.offset !== routeEnd)
-                fail('Invalid Instance route body length.');
+            reader.offset = routeEnd;
             const sourceNodeGeneration = reader.nonZeroU64('sourceNodeGeneration');
             const sourceNodeRid = reader.rid('sourceNodeRid');
             const sourceSpotId = reader.optionalRid('sourceSpotId');
@@ -928,17 +917,17 @@ function decodeStatefulHeader(frame, payloadFrame, metadataFrame) {
                 low: reader.u64('operation.low')
             };
             const operationKind = operationValue === 1 ? 'send' : 'request';
-            if (version === INSTANCE_ROUTE_VERSION &&
+            if (generatedRoute.routeKind === 'ready' &&
                 ((operationKind === 'send' && (operation.high !== 0n || operation.low !== 0n)) ||
                     (operationKind === 'request' && operation.high === 0n && operation.low === 0n))) {
                 fail('Invalid Instance operation identity.');
             }
-            if (version === INSTANCE_ACTIVATION_VERSION &&
+            if (generatedRoute.routeKind === 'coldActivation' &&
                 operation.high === 0n &&
                 operation.low === 0n) {
                 fail('Instance activation requires a non-zero operation identity.');
             }
-            const deadlineUnixMs = version === INSTANCE_ACTIVATION_VERSION ? reader.nonZeroU64('deadlineUnixMs') : undefined;
+            const deadlineUnixMs = generatedRoute.routeKind === 'coldActivation' ? generatedRoute.deadlineUnixMs : undefined;
             const replyRouteId = operationKind === 'request' ? reader.nonZeroU64('replyRouteId') : undefined;
             reader.end();
             const common = {
@@ -950,12 +939,12 @@ function decodeStatefulHeader(frame, payloadFrame, metadataFrame) {
                 operation,
                 ...(replyRouteId === undefined ? {} : { replyRouteId })
             };
-            return version === INSTANCE_ROUTE_VERSION
+            return generatedRoute.routeKind === 'ready'
                 ? {
                     ...common,
                     activation: 'ready',
                     route: route,
-                    instanceIntent: generatedReadyRoute.instanceIntent === 'true'
+                    instanceIntent: generatedRoute.instanceIntent === 'true'
                 }
                 : {
                     ...common,
@@ -1375,10 +1364,6 @@ function rid(value, name) {
 function text8(value, name) {
     return sized8(value, name);
 }
-function text16(value, name) {
-    const bytes = (0, service_wire_binary_primitives_1.encodeCanonicalServiceWireText)(value, name, 0xffff, outOfRange);
-    return concat(u16(bytes.byteLength), bytes);
-}
 function optionalRid(value) {
     return value === undefined ? Buffer.of(0) : rid(value, 'sourceSpotId');
 }
@@ -1428,6 +1413,16 @@ function requireFlags(actual, expected) {
 function concat(...parts) {
     return Buffer.concat(parts.map((part) => Buffer.from(part)));
 }
+function decodeCanonicalInstanceRoute(bytes) {
+    try {
+        return (0, service_wire_codec_generated_1.decodeInstanceRouteV1)(bytes, STATEFUL_MESSAGE_CONTEXT);
+    }
+    catch (error) {
+        if (error instanceof RangeError)
+            throw new service_wire_m6a_codec_1.ServiceWireProtocolError(error.message);
+        throw error;
+    }
+}
 function fail(message) {
     throw new service_wire_m6a_codec_1.ServiceWireProtocolError(message);
 }
@@ -2009,22 +2004,9 @@ class FrozenReader {
     }
     instanceRoute() {
         const start = this.offset;
-        const kind = this.u8('instanceRouteKind');
-        if (kind < 1 || kind > 2)
-            fail('Invalid Instance route kind.');
-        const body = this.body16('Instance route');
-        if (kind === INSTANCE_ROUTE_VERSION) {
-            (0, service_wire_codec_generated_1.decodeInstanceRouteV1)(this.bytes.subarray(start, this.offset), STATEFUL_MESSAGE_CONTEXT);
-            return;
-        }
-        body.rid8('targetNodeRid');
-        body.nonZeroU64('targetNodeGeneration');
-        body.text8('targetSpotId');
-        body.text8('targetMeshName');
-        body.text8('stableType');
-        body.text8('targetDescriptorVersion');
-        body.nonZeroU64('deadlineUnixMs');
-        body.end('Instance route');
+        this.u8('instanceRouteKind');
+        this.body16('Instance route');
+        decodeCanonicalInstanceRoute(this.bytes.subarray(start, this.offset));
     }
     relocationObject() {
         const kind = this.u8('relocationObjectKind');

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

@@ -1,3 +1,4 @@
+import type { ServiceLivenessConnection } from './service-liveness-registry';
 export type ServiceNodeState = 'preparing' | 'serving' | 'retiring' | 'draining' | 'stopped' | 'error';
 export type ServiceObjectRole = 'none' | 'client' | 'server';
 export interface ServiceChannelDescriptor {
@@ -23,9 +24,15 @@ export interface ServiceNodeDescriptor {
     readonly activeCapacityUsed: number;
     readonly pendingCapacityUsed: number;
 }
-export interface AdmittedServicePeer {
+interface ServiceRouteAdmission {
     readonly descriptor: ServiceNodeDescriptor;
-    readonly connectionId: string;
+    readonly descriptorBytes?: Uint8Array;
+    readonly connectionId?: string | bigint;
+    readonly remoteAdmitReceived?: boolean;
+}
+export interface AdmittedServicePeer extends ServiceRouteAdmission {
+    readonly connectionId: string | bigint;
+    readonly liveness?: ServiceLivenessConnection;
 }
 export interface ServicePeerAdmissionExpectation {
     readonly endpoint?: string;
@@ -44,15 +51,19 @@ export declare class ServiceTopologyRegistry {
     constructor(local: ServiceNodeDescriptor);
     localDescriptor(): ServiceNodeDescriptor;
     publishLocal(descriptor: ServiceNodeDescriptor): void;
-    admit(descriptor: ServiceNodeDescriptor, connectionId: string, expected?: ServicePeerAdmissionExpectation): PeerAdmissionResult;
-    disconnect(nodeRoutingId: string, connectionId: string): boolean;
+    admit(descriptor: ServiceNodeDescriptor, connectionId: string | bigint, expected?: ServicePeerAdmissionExpectation, admitLiveness?: () => ServiceLivenessConnection, command?: number, descriptorBytes?: Uint8Array): PeerAdmissionResult;
+    disconnect(nodeRoutingId: string, connectionId: string | bigint): boolean;
     peer(nodeRoutingId: string): AdmittedServicePeer | undefined;
+    routeAdmission(nodeRoutingId: string): ServiceRouteAdmission | undefined;
+    admittedPeer(nodeRoutingId: string): AdmittedServicePeer | undefined;
     peers(): readonly AdmittedServicePeer[];
     private peersCore;
     notRequiredPeers(): readonly ServiceNodeDescriptor[];
     replaceDiscoveredNotRequired(descriptors: readonly ServiceNodeDescriptor[]): void;
     forgetNotRequired(nodeRoutingId: string): void;
     knownDescriptor(nodeRoutingId: string): ServiceNodeDescriptor | undefined;
+    isObjectClientNodeDirectTarget(nodeRoutingId: string): boolean;
+    private knownPeerDescriptor;
     hasKnownChannelTarget(channelName: string): boolean;
     private remember;
     selectChannel(channelName: string, isReady?: (peer: AdmittedServicePeer) => boolean): AdmittedServicePeer | undefined;
@@ -70,3 +81,4 @@ export declare class ServiceTopologyRegistry {
 }
 export declare function validateDescriptor(descriptor: ServiceNodeDescriptor): void;
 export declare function sameServiceNodeDescriptor(left: ServiceNodeDescriptor, right: ServiceNodeDescriptor): boolean;
+export {};