@zlink-systems/framework 0.27.0 → 0.29.0

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

@@ -430,8 +430,8 @@ class ServiceTerminalOperationRegistry {
     constructor(operations = new operation_registry_1.OperationRegistry()) {
         this.operations = operations;
     }
-    register(timeoutMs, timeoutOwner = 'registry') {
-        return this.operations.register(timeoutMs, timeoutOwner);
+    register(timeoutMs, timeoutOwner = 'registry', context) {
+        return this.operations.register(timeoutMs, timeoutOwner, context);
     }
     reply(id, value) {
         return this.operations.complete(id, value);
@@ -445,6 +445,9 @@ class ServiceTerminalOperationRegistry {
     isPending(id) {
         return this.operations.isPending(id);
     }
+    context(id) {
+        return this.operations.context(id);
+    }
     get size() {
         return this.operations.size;
     }

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

@@ -125,9 +125,6 @@ export type ServiceInstanceAuthorityRead = {
 export type ServiceInstanceAuthorityReserve = {
     readonly kind: 'reserved';
     readonly reservation: ServiceInstanceActivationReservation;
-} | {
-    readonly kind: 'ready';
-    readonly route: ServiceInstanceRouteFence;
 };
 /**
  * Synchronous authority port used by the raw ingress turn. An asynchronous
@@ -161,10 +158,6 @@ export interface ServiceAsyncInstanceActivationAuthority {
     complete(target: ServiceInstanceActivationTarget, route: ServiceInstanceRouteFence): Promise<ServiceInstanceRouteFence>;
     abort(target: ServiceInstanceActivationTarget, reservation: ServiceInstanceActivationReservation): Promise<void>;
 }
-export declare class ServiceInstanceActivationRedirectError extends Error {
-    readonly route: ServiceInstanceRouteFence;
-    constructor(route: ServiceInstanceRouteFence);
-}
 export interface ServiceUserSpotOperationResult {
     readonly terminalResult: number;
     readonly failureCode: number;
@@ -326,7 +319,7 @@ export declare class ServiceStatefulRuntime {
     private beginInstanceAuthorityOperation;
     private completeInstanceAuthorityOperation;
     private completeInstanceApplicationWaitersIfQuiescent;
-    private relayMissingInstanceActivation;
+    private finishMissingInstanceActivationFailure;
     private requireInstanceActivation;
     private requireReadyInstanceApplicationRoute;
     private validateInstanceIngress;

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ServiceStatefulRuntime = exports.ServiceInstanceActivationRedirectError = void 0;
+exports.ServiceStatefulRuntime = void 0;
 exports.statefulMailboxData = statefulMailboxData;
 const stream_wire_1 = require("@zlink-systems/stream-wire");
 const node_async_hooks_1 = require("node:async_hooks");
@@ -31,15 +31,6 @@ const SPOT_MOVING = 34;
 const USER_SPOT_OPERATION_CAPACITY = 65_536;
 const USER_SPOT_OPERATION_REPLAY_RETENTION_MS = 5 * 60_000;
 const ACTOR_ROUTE_NOT_FOUND = 1;
-class ServiceInstanceActivationRedirectError extends Error {
-    route;
-    constructor(route) {
-        super(`Instance Spot '${route.targetSpotId}' is owned by '${route.targetNodeRid}'.`);
-        this.route = route;
-        this.name = 'ServiceInstanceActivationRedirectError';
-    }
-}
-exports.ServiceInstanceActivationRedirectError = ServiceInstanceActivationRedirectError;
 /**
  * Owns M6B routing, identity fences and terminal operations. Application turns
  * remain in the common mailbox, where a claimed Spot or Actor owner is serial.
@@ -410,7 +401,7 @@ class ServiceStatefulRuntime {
         const committed = await authority.commit(target, reservation, spot);
         if (committed.kind !== 'committed') {
             this.registry.closeSpot(spot.ref);
-            throw new ServiceInstanceActivationRedirectError(committed.route);
+            throw activationRefused();
         }
         return this.finishRecoveredInstanceActivation(envelope, committed.route, expectedCurrentRoute);
     }
@@ -1116,6 +1107,10 @@ class ServiceStatefulRuntime {
                 const metadata = (record.flags & service_stateful_wire_codec_1.M6bServiceWireFlag.metadata) !== 0;
                 decoded = (0, service_stateful_wire_codec_1.decodeStatefulHeader)(record.parts[0], record.parts[metadata ? 2 : 1], metadata ? record.parts[1] : undefined);
             }
+            if (decoded.kind === 'instanceSpot' &&
+                (decoded.operationKind === 'request') !== (record.requestSequence !== undefined)) {
+                return 'protocolError';
+            }
             const hasPayload = [
                 'spotSend',
                 'spotRequest',
@@ -1164,6 +1159,12 @@ class ServiceStatefulRuntime {
                 return await this.handleIngress(record, decoded, payloadFrame, metadataFrame, canonicalActorJoin, canonicalPayload);
             }
             catch (error) {
+                if (decoded.kind === 'instanceSpot' &&
+                    decoded.activation === 'missing' &&
+                    (error instanceof contracts_1.ZLinkFrameworkException || error instanceof service_stateful_registry_1.ServiceStaleGenerationError)) {
+                    this.finishMissingInstanceActivationFailure(record, decoded, error);
+                    return 'infrastructure';
+                }
                 const correlation = statefulCorrelation(decoded);
                 if (correlation !== undefined) {
                     const result = failure(error);
@@ -1254,7 +1255,7 @@ class ServiceStatefulRuntime {
                     sourceSpotId: record.sourceSpotId,
                     targetSpot: record.target.spot,
                     ...(record.kind === 'spotRequest'
-                        ? { reply: this.replyPort(ingress, record.correlation, 'spotRequest') }
+                        ? { reply: this.replyPort(ingress, record.correlation) }
                         : {})
                 });
             }
@@ -1290,7 +1291,7 @@ class ServiceStatefulRuntime {
                         originalReplyRouteId: ingress.requestSequence ?? 0n
                     },
                     ...(record.kind === 'actorRequest'
-                        ? { reply: this.replyPort(ingress, record.correlation, 'actorRequest') }
+                        ? { reply: this.replyPort(ingress, record.correlation) }
                         : {})
                 });
             }
@@ -1324,10 +1325,10 @@ class ServiceStatefulRuntime {
                 return this.handleUserSpotOperation(ingress, record);
         }
     }
-    enqueueInstanceSpot(ingress, record, payloadFrame, metadataFrame) {
+    enqueueInstanceSpot(ingress, record, payloadFrame, metadataFrame, localReply) {
         if (record.activation === 'missing' && this.asyncInstanceAuthority !== undefined) {
             const ownedIngress = shareIngressOwnership(ingress);
-            void this.continueMissingInstanceActivation(ownedIngress, record, payloadFrame, undefined, metadataFrame).finally(() => ownedIngress.applicationJobOwner?.close());
+            void this.continueMissingInstanceActivation(ownedIngress, record, payloadFrame, localReply, metadataFrame).finally(() => ownedIngress.applicationJobOwner?.close());
             return 'infrastructure';
         }
         if (record.activation === 'ready' &&
@@ -1344,7 +1345,7 @@ class ServiceStatefulRuntime {
                 objectGeneration: spot.ref.generation
             }
             : this.instanceApplicationTarget(record);
-        return this.enqueueActivatedInstanceSpot(ingress, record, payloadFrame, spot, undefined, this.instanceApplicationTerminalCompletion(applicationTarget), metadataFrame);
+        return this.enqueueActivatedInstanceSpot(ingress, record, payloadFrame, spot, localReply, this.instanceApplicationTerminalCompletion(applicationTarget), metadataFrame);
     }
     needsInstanceApplicationMaterialization(ingress, record) {
         const lifecycle = this.instanceApplicationLifecycle;
@@ -1376,7 +1377,10 @@ class ServiceStatefulRuntime {
                 return 'application';
         }
         const directReply = record.operationKind === 'request'
-            ? (localReply ?? this.replyPort(ingress, record.replyRouteId, 'instanceSpotRequest'))
+            ? (localReply ??
+                (ingress.requestSequence === undefined
+                    ? undefined
+                    : this.replyPort(ingress, record.replyRouteId)))
             : undefined;
         const applicationTarget = applicationTargetOverride ??
             (record.activation === 'missing'
@@ -1410,7 +1414,7 @@ class ServiceStatefulRuntime {
             ...(metadataFrame === undefined ? {} : { applicationMetadata: metadataFrame }),
             ...(terminalCompletion === undefined ? {} : { onTerminalCompletion: terminalCompletion }),
             ...(onHandlerTurnStarted === undefined ? {} : { onHandlerTurnStarted }),
-            ...(record.operationKind === 'request'
+            ...(record.operationKind === 'request' && directReply !== undefined
                 ? {
                     reply: onTerminalCompletion === undefined
                         ? directReply
@@ -1442,27 +1446,7 @@ class ServiceStatefulRuntime {
             }
         }
         catch (error) {
-            let terminalError = error;
-            if (error instanceof ServiceInstanceActivationRedirectError && !this.closed) {
-                try {
-                    await this.relayMissingInstanceActivation(record, payloadFrame, error.route, ingress, localReply, metadataFrame);
-                    return;
-                }
-                catch (relayError) {
-                    terminalError = relayError;
-                }
-            }
-            if (record.operationKind !== 'request')
-                return;
-            const result = failure(terminalError);
-            if (localReply !== undefined) {
-                localReply(result.terminalResult, result.failureCode);
-            }
-            else {
-                if (record.replyRouteId === undefined)
-                    return;
-                this.replyWire(ingress, record.replyRouteId, result.terminalResult, result.failureCode);
-            }
+            this.finishMissingInstanceActivationFailure(ingress, record, error, localReply);
         }
     }
     async continueReadyInstanceMaterialization(ingress, record, payloadFrame, metadataFrame) {
@@ -1492,7 +1476,9 @@ class ServiceStatefulRuntime {
             }
         }
         catch (error) {
-            if (record.operationKind !== 'request' || record.replyRouteId === undefined)
+            if (record.operationKind !== 'request' ||
+                record.replyRouteId === undefined ||
+                ingress.requestSequence === undefined)
                 return;
             const result = failure(error);
             this.replyWire(ingress, record.replyRouteId, result.terminalResult, result.failureCode);
@@ -1545,8 +1531,11 @@ class ServiceStatefulRuntime {
         return { onTerminalCompletion, onHandlerTurnStarted };
     }
     instanceApplicationTerminalCompletion(target) {
+        const lifecycle = this.instanceApplicationLifecycle;
+        if (lifecycle === undefined)
+            return undefined;
         return async () => {
-            const authorityReleased = (await this.instanceApplicationLifecycle?.completeTerminal(target)) ?? false;
+            const authorityReleased = await lifecycle.completeTerminal(target);
             if (!authorityReleased)
                 return;
             const current = this.instanceIntents.get(target.targetSpotId);
@@ -1601,39 +1590,33 @@ class ServiceStatefulRuntime {
         for (const waiter of waiters)
             waiter();
     }
-    async relayMissingInstanceActivation(record, payloadFrame, route, ingress, localReply, metadataFrame) {
-        const remainingMs = Number(record.deadlineUnixMs - BigInt(Date.now()));
-        if (remainingMs <= 0) {
-            throw new service_stateful_registry_1.ServiceStaleGenerationError('spot', route.targetSpotId);
-        }
-        const redirectedTarget = {
-            ...record.target,
-            targetNodeRid: route.targetNodeRid,
-            targetNodeGeneration: route.targetNodeGeneration,
-            targetSpotId: route.targetSpotId
-        };
-        if (record.operationKind === 'send') {
-            const submitted = await this.submitOneWay(route.targetNodeRid, instanceOperationParts([
-                (0, service_stateful_wire_codec_1.encodeInstanceSpotActivationHeader)(redirectedTarget, this.nodeGeneration, this.nodeRid, record.sourceSpotId, 'send', record.operation, record.deadlineUnixMs, undefined, metadataFrame !== undefined),
-                payloadFrame
-            ], metadataFrame));
-            if (submitted !== runtime_values_1.SubmitResult.Ok) {
-                throw new Error(`Instance activation redirect was not admitted: ${submitted}.`);
+    finishMissingInstanceActivationFailure(ingress, record, error, localReply) {
+        if (record.operationKind === 'request') {
+            if (record.deadlineUnixMs <= BigInt(Date.now()))
+                return;
+            const result = failure(error);
+            if (localReply !== undefined) {
+                localReply(result.terminalResult, result.failureCode);
+            }
+            else if (ingress.requestSequence !== undefined && record.replyRouteId !== undefined) {
+                this.replyWire(ingress, record.replyRouteId, result.terminalResult, result.failureCode);
             }
             return;
         }
-        const pending = this.operations.register(remainingMs);
-        this.submitRequest(pending, route.targetNodeRid, instanceOperationParts([
-            (0, service_stateful_wire_codec_1.encodeInstanceSpotActivationHeader)(redirectedTarget, this.nodeGeneration, this.nodeRid, record.sourceSpotId, 'request', record.operation, record.deadlineUnixMs, pending.id, metadataFrame !== undefined),
-            payloadFrame
-        ], metadataFrame), remainingMs, 'instanceSpotRequest');
-        const result = await pending.promise;
-        if (localReply !== undefined) {
-            localReply(result.terminalResult, result.failureCode, result.payload);
-            return;
-        }
-        if (record.replyRouteId !== undefined) {
-            this.replyWire(ingress, record.replyRouteId, result.terminalResult, result.failureCode, result.payload);
+        const reporter = this.dispatchErrors;
+        if (reporter?.captureEnabled() === true) {
+            reporter.report({
+                surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.InstanceSpot,
+                messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send,
+                reason: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.StaleTarget,
+                action: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop,
+                meshName: this.dispatchErrorMeshName,
+                sourceRid: record.sourceNodeRid,
+                spotId: record.target.targetSpotId,
+                instanceSpotType: record.target.stableType,
+                activationState: 'activating',
+                error
+            });
         }
     }
     requireInstanceActivation(ingress, record) {
@@ -1731,12 +1714,9 @@ class ServiceStatefulRuntime {
             return local;
         }
         if (current.kind === 'ready') {
-            throw new ServiceInstanceActivationRedirectError(current.route);
+            throw activationRefused();
         }
         const reserved = authority.reserve(target, record.operation, record.deadlineUnixMs);
-        if (reserved.kind === 'ready') {
-            throw new ServiceInstanceActivationRedirectError(reserved.route);
-        }
         let activation;
         try {
             activation = this.activateInstanceSpot(target.targetSpotId, target.stableType, reserved.reservation.attempt, reserved.reservation.authorityOwnerGeneration);
@@ -1749,7 +1729,7 @@ class ServiceStatefulRuntime {
         if (committed.kind === 'lost') {
             if (activation.created)
                 this.registry.closeSpot(activation.spot.ref);
-            throw new ServiceInstanceActivationRedirectError(committed.route);
+            throw activationRefused();
         }
         if (!routeMatchesLocal(committed.route, activation.spot, this.nodeRid, this.nodeGeneration)) {
             if (activation.created)
@@ -1803,12 +1783,12 @@ class ServiceStatefulRuntime {
                 }
             };
         }
+        if (current.kind === 'ready' && current.route.targetNodeRid !== this.nodeRid) {
+            throw activationRefused();
+        }
         if (current.kind === 'ready' &&
             current.authority !== undefined &&
             (0, service_authority_payload_codec_1.decodeServiceClosingSpotAuthority)(current.authority.payload) !== undefined) {
-            if (current.route.targetNodeRid !== this.nodeRid) {
-                throw new ServiceInstanceActivationRedirectError(current.route);
-            }
             if (current.route.targetNodeGeneration !== this.nodeGeneration ||
                 (local !== undefined &&
                     !routeMatchesLocal(current.route, local, this.nodeRid, this.nodeGeneration)) ||
@@ -1821,17 +1801,11 @@ class ServiceStatefulRuntime {
             };
         }
         if (!this.acceptsLocalMissingInstancePlacement()) {
-            if (current.kind === 'ready' && current.route.targetNodeRid !== this.nodeRid) {
-                throw new ServiceInstanceActivationRedirectError(current.route);
-            }
             // A draining or retiring node must not create a successor generation
             // from a stale client route while relocation is publishing its target.
             throw new service_stateful_registry_1.ServiceStaleGenerationError('spot', target.targetSpotId);
         }
         if (current.kind === 'ready') {
-            if (current.route.targetNodeRid !== this.nodeRid) {
-                throw new ServiceInstanceActivationRedirectError(current.route);
-            }
             if (current.route.targetNodeGeneration !== this.nodeGeneration) {
                 throw new service_stateful_registry_1.ServiceStaleGenerationError('spot', target.targetSpotId);
             }
@@ -1867,16 +1841,9 @@ class ServiceStatefulRuntime {
                 await lifecycle.discard(target);
                 materialized = lifecycle.isMaterialized(target);
             }
-            // The authority can still be in a Creating reservation after the local
-            // registry exposes the activation. Allow the authority reserve operation
-            // to join that attempt instead of treating the local projection as stale.
-            // A newer reservation can also become visible after an explicit close
-            // releases authority but before local disposal removes the old
-            // projection. The close gate serializes that replacement; rejecting it
-            // here turns a valid next-generation Instance intent into a stale-route
-            // failure.
-            // If disposal did not remove an orphaned materialization, keep fencing
-            // it instead of admitting work into two application generations.
+            // The local projection does not decide reservation ownership. Preserve
+            // the Creating fence for Reserve, which refuses a competing attempt.
+            // Keep fencing an orphan that disposal did not remove.
             if ((!joinsCreating && current.kind !== 'missing') ||
                 (!joinsCreating && materialized !== false && !materializing)) {
                 throw new service_stateful_registry_1.ServiceStaleGenerationError('spot', target.targetSpotId);
@@ -1901,9 +1868,6 @@ class ServiceStatefulRuntime {
         finally {
             deadline.close();
         }
-        if (reserved.kind === 'ready') {
-            throw new ServiceInstanceActivationRedirectError(reserved.route);
-        }
         if (this.closed || record.deadlineUnixMs < BigInt(Date.now())) {
             await authority.abort(target, reserved.reservation);
             throw new service_stateful_registry_1.ServiceStaleGenerationError('spot', target.targetSpotId);
@@ -1932,7 +1896,7 @@ class ServiceStatefulRuntime {
             if (activation.created)
                 this.registry.closeSpot(activation.spot.ref);
             await this.instanceApplicationLifecycle?.discard(target);
-            throw new ServiceInstanceActivationRedirectError(committed.route);
+            throw activationRefused();
         }
         if (!routeMatchesLocal(committed.route, activation.spot, this.nodeRid, this.nodeGeneration)) {
             if (activation.created)
@@ -1960,7 +1924,7 @@ class ServiceStatefulRuntime {
         const confirmed = await authority.read(target);
         if (confirmed.kind !== 'ready' || !sameInstanceRoute(confirmed.route, route)) {
             if (confirmed.kind === 'ready' && confirmed.route.targetNodeRid !== this.nodeRid) {
-                throw new ServiceInstanceActivationRedirectError(confirmed.route);
+                throw activationRefused();
             }
             throw new service_stateful_registry_1.ServiceStaleGenerationError('spot', target.targetSpotId);
         }
@@ -2056,7 +2020,7 @@ class ServiceStatefulRuntime {
             kindData: control,
             ...(canonicalApplicationPayload === undefined ? {} : { canonicalApplicationPayload }),
             reply: (terminalResult, failureCode, replyPayload, tail) => {
-                return this.replyPort(ingress, record.correlation, 'actorJoin')(terminalResult, failureCode, replyPayload, tail);
+                return this.replyPort(ingress, record.correlation)(terminalResult, failureCode, replyPayload, tail);
             }
         });
     }
@@ -2538,20 +2502,20 @@ class ServiceStatefulRuntime {
         }
         return accepted;
     }
-    replyPort(ingress, correlation, operationKind) {
+    replyPort(ingress, correlation) {
         if (correlation === undefined)
             throw new service_wire_m6a_codec_1.ServiceWireProtocolError('Request correlation is missing.');
         return (terminalResult, failureCode, payload, tail) => {
             this.replyWire(ingress, correlation, terminalResult, failureCode, payload, tail);
-            void operationKind;
             return true;
         };
     }
     replyWire(ingress, correlation, terminalResult, failureCode, payload, tail) {
-        this.raw.replyService(ingress, [
+        const parts = [
             (0, service_stateful_wire_codec_1.encodeStatefulReply)(correlation, terminalResult, failureCode, tail),
             ...(payload === undefined ? [] : [(0, service_wire_m6a_codec_1.encodeApplicationPayload)(payload)])
-        ]);
+        ];
+        this.raw.replyService(ingress, parts);
     }
     handleUserSpotOperation(ingress, record) {
         if (ingress.requestSequence === undefined ||
@@ -3094,24 +3058,11 @@ class ServiceStatefulRuntime {
             return;
         }
         if (decoded.kind === 'instanceSpot') {
-            if (decoded.activation === 'missing' && this.asyncInstanceAuthority !== undefined) {
-                void this.continueMissingInstanceActivation(ingress, decoded, payloadFrame, localReply);
-                return;
-            }
-            try {
-                const activation = this.requireInstanceActivation(ingress, decoded);
-                this.enqueueApplicationFrame(ingress, `spot:${activation.ref.spotId}`, payloadFrame, {
-                    receiveKind: service_runtime_contracts_1.ReceiveKind.InstanceSpotActivation,
-                    operationKind: service_runtime_contracts_1.OperationKind.InstanceSpotRequest,
-                    correlation: pending.id,
-                    ...(decoded.sourceSpotId === undefined ? {} : { sourceSpotId: decoded.sourceSpotId }),
-                    targetSpot: activation.ref,
-                    reply: localReply
-                });
-            }
-            catch (error) {
-                this.operations.reply(pending.id, failure(error));
-            }
+            const hasMetadata = (ingress.flags & service_stateful_wire_codec_1.M6bServiceWireFlag.metadata) !== 0;
+            const metadataFrame = hasMetadata
+                ? (0, service_metadata_codec_1.validateServiceMetadataFrame)(ingress.parts[1])
+                : undefined;
+            this.enqueueInstanceSpot(ingress, decoded, ingress.parts[hasMetadata ? 2 : 1], metadataFrame, localReply);
             return;
         }
         this.operations.reply(pending.id, {
@@ -3292,9 +3243,7 @@ class ServiceStatefulRuntime {
             ...(wire.correlation === undefined ? {} : { correlation: wire.correlation }),
             sourceSpotId: wire.sourceSpotId,
             targetSpot: wire.target.spot,
-            ...(wire.kind === 'spotRequest'
-                ? { reply: this.replyPort(ingress, wire.correlation, 'spotRequest') }
-                : {})
+            ...(wire.kind === 'spotRequest' ? { reply: this.replyPort(ingress, wire.correlation) } : {})
         });
     }
     async drainSpotMessageFollow(state) {
@@ -3671,6 +3620,9 @@ function actorLocation(actor) {
         membershipEpoch: actor.membershipEpoch
     };
 }
+function activationRefused() {
+    return new contracts_1.ZLinkFrameworkException(contracts_1.ZLinkFrameworkErrorKind.Unavailable, 'Instance cold activation authority was refused.');
+}
 function failure(error) {
     if (error instanceof service_stateful_registry_1.ServiceStaleGenerationError) {
         return (0, framework_errors_internal_1.internalFrameworkWireReply)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale);

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

@@ -105,8 +105,6 @@ export type ServiceWireRelocationObject = {
     readonly spotId: string;
     readonly objectGeneration: bigint;
 };
-/** Shared CRC-32C wire bounds for the direct relocation payload transfer. */
-export declare const RELOCATION_PAYLOAD_TOTAL_LENGTH_MAX = 274877906944n;
 export declare const RELOCATION_PAYLOAD_CHUNK_COUNT_MAX = 4096;
 export { RELOCATION_STATE_CHUNK_DATA_MAX_BYTES } from '../../contracts/Configuration/InternalDefaults';
 interface ServiceWireRelocationBase {
@@ -576,15 +574,6 @@ export declare function decodeMaintenanceReplyRelayAck(frame: Uint8Array): Servi
 export declare function decodeStatefulReply(frame: Uint8Array, expectedCorrelation: bigint, operationKind: 'spotRequest' | 'actorRequest' | 'actorLookup' | 'actorDestroy' | 'actorJoin' | 'streamBind' | 'streamUnbind' | 'instanceSpotRequest' | 'userSpotCreate' | 'userSpotClose' | 'actorCreate', hasPayload?: boolean): ServiceStatefulReply;
 export declare function sessionBindingFromWire(actor: ServiceActorRef, sessionRid: string, sessionOwnerNodeRid: string, generation: bigint, membershipEpoch: bigint, sessionOwnerNodeGeneration?: bigint, sessionOwnerId?: string, sessionOwnerLeaseGeneration?: bigint): ServiceSessionBinding;
 export declare function decodeServiceWireFrozenRecord(bytes: Uint8Array): ServiceWireFrozenRecord;
-/**
- * Consumes exactly one canonical frozen record at `offset`.  Relocation
- * saved-work is a vector of back-to-back records, so its boundary is the
- * record grammar itself rather than an enclosing length field.
- */
-export declare function decodeServiceWireFrozenRecordPrefix(bytes: Uint8Array, offset?: number): {
-    readonly record: ServiceWireFrozenRecord;
-    readonly length: number;
-};
 export declare function encodeServiceWireFrozenRecord(record: ServiceWireFrozenRecord): Buffer;
 export declare function encodeServiceWireFrozenActorApplicationRecord(input: {
     readonly source: ServiceWireRequestSourceFence;

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.M6bServiceWireFlag = exports.RELOCATION_STATE_CHUNK_DATA_MAX_BYTES = exports.RELOCATION_PAYLOAD_CHUNK_COUNT_MAX = exports.RELOCATION_PAYLOAD_TOTAL_LENGTH_MAX = exports.M6bServiceWireCommand = void 0;
+exports.M6bServiceWireFlag = exports.RELOCATION_STATE_CHUNK_DATA_MAX_BYTES = exports.RELOCATION_PAYLOAD_CHUNK_COUNT_MAX = exports.M6bServiceWireCommand = void 0;
 exports.serviceSessionRelocationIdentityKey = serviceSessionRelocationIdentityKey;
 exports.encodeSpotHeader = encodeSpotHeader;
 exports.encodeActorHeader = encodeActorHeader;
@@ -33,7 +33,6 @@ exports.decodeMaintenanceReplyRelayAck = decodeMaintenanceReplyRelayAck;
 exports.decodeStatefulReply = decodeStatefulReply;
 exports.sessionBindingFromWire = sessionBindingFromWire;
 exports.decodeServiceWireFrozenRecord = decodeServiceWireFrozenRecord;
-exports.decodeServiceWireFrozenRecordPrefix = decodeServiceWireFrozenRecordPrefix;
 exports.encodeServiceWireFrozenRecord = encodeServiceWireFrozenRecord;
 exports.encodeServiceWireFrozenActorApplicationRecord = encodeServiceWireFrozenActorApplicationRecord;
 const stream_wire_1 = require("@zlink-systems/stream-wire");
@@ -55,8 +54,6 @@ const MAGIC_0 = service_wire_constants_generated_1.SERVICE_WIRE_MAGIC[0];
 const MAGIC_1 = service_wire_constants_generated_1.SERVICE_WIRE_MAGIC[1];
 const MAJOR = service_wire_constants_generated_1.SERVICE_WIRE_MAJOR;
 exports.M6bServiceWireCommand = service_wire_constants_generated_1.ServiceWireCommand;
-/** Shared CRC-32C wire bounds for the direct relocation payload transfer. */
-exports.RELOCATION_PAYLOAD_TOTAL_LENGTH_MAX = 274877906944n;
 exports.RELOCATION_PAYLOAD_CHUNK_COUNT_MAX = 4096;
 var InternalDefaults_2 = require("../../contracts/Configuration/InternalDefaults");
 Object.defineProperty(exports, "RELOCATION_STATE_CHUNK_DATA_MAX_BYTES", { enumerable: true, get: function () { return InternalDefaults_2.RELOCATION_STATE_CHUNK_DATA_MAX_BYTES; } });
@@ -1623,25 +1620,6 @@ function decodeServiceWireFrozenRecord(bytes) {
     reader.end('frozen record');
     return { ...record, canonicalBytes: Buffer.from(bytes) };
 }
-/**
- * Consumes exactly one canonical frozen record at `offset`.  Relocation
- * saved-work is a vector of back-to-back records, so its boundary is the
- * record grammar itself rather than an enclosing length field.
- */
-function decodeServiceWireFrozenRecordPrefix(bytes, offset = 0) {
-    if (!Number.isSafeInteger(offset) || offset < 0 || offset >= bytes.byteLength) {
-        fail('Frozen record offset is outside the encoded bytes.');
-    }
-    const reader = new FrozenReader(bytes.subarray(offset));
-    const record = decodeServiceWireFrozenRecordFrom(reader);
-    return {
-        record: {
-            ...record,
-            canonicalBytes: Buffer.from(bytes.subarray(offset, offset + reader.position))
-        },
-        length: reader.position
-    };
-}
 function decodeServiceWireFrozenRecordFrom(reader) {
     const recordKind = reader.u8('recordKind');
     if (recordKind < 1 || recordKind > 14)

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

@@ -58,7 +58,12 @@ export declare class ServiceTopologyRegistry {
     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;
+    selectObjectPlacementWithStatus(stableType: string, isReady?: (descriptor: ServiceNodeDescriptor) => boolean): {
+        readonly status: ServiceObjectPlacementStatus;
+        readonly descriptor?: ServiceNodeDescriptor;
+    };
     objectPlacementStatus(stableType: string, isReady?: (descriptor: ServiceNodeDescriptor) => boolean): ServiceObjectPlacementStatus;
+    private objectPlacementCandidates;
     instanceSpotPlacementTypes(): readonly string[];
     private selectWeightedCycle;
     private rebuildSelections;

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

@@ -181,21 +181,22 @@ class ServiceTopologyRegistry {
             .map(clonePeer), (peer) => peer.descriptor.placementWeight, (peer) => peer.descriptor.nodeRoutingId, (left, right) => compareOrdinal(left.descriptor.nodeRoutingId, right.descriptor.nodeRoutingId), isReady);
     }
     selectObjectPlacement(stableType, isReady = () => true) {
+        return this.selectObjectPlacementWithStatus(stableType, isReady).descriptor;
+    }
+    selectObjectPlacementWithStatus(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);
+        const candidates = this.objectPlacementCandidates(stableType, isReady);
+        if (candidates.status !== 'available')
+            return { status: candidates.status };
+        const descriptor = this.selectWeightedCycle(`object:${stableType}`, () => this.objectPlacementCandidates(stableType).eligible.map(cloneDescriptor), (descriptor) => descriptor.placementWeight, (descriptor) => descriptor.nodeRoutingId, (left, right) => compareOrdinal(left.nodeRoutingId, right.nodeRoutingId), isReady);
+        return descriptor === undefined
+            ? { status: 'unavailable' }
+            : { status: 'available', descriptor };
     }
     objectPlacementStatus(stableType, isReady = () => true) {
+        return this.objectPlacementCandidates(stableType, isReady).status;
+    }
+    objectPlacementCandidates(stableType, isReady = () => true) {
         requireText(stableType, 'stableType');
         const capability = `object-type:${stableType}`;
         const supported = [
@@ -205,15 +206,13 @@ class ServiceTopologyRegistry {
             descriptor.objectRole === 'server' &&
             descriptor.protocolCapabilities.includes(capability));
         if (supported.length === 0)
-            return 'unsupported';
+            return { status: 'unsupported', eligible: [] };
         const withCapacity = supported.filter((descriptor) => descriptor.activeCapacityUsed < descriptor.activeCapacityLimit &&
             descriptor.pendingCapacityUsed < descriptor.pendingCapacityLimit);
         if (withCapacity.length === 0)
-            return 'capacity';
+            return { status: 'capacity', eligible: [] };
         const weighted = withCapacity.filter((descriptor) => descriptor.placementWeight > 0);
-        if (weighted.length === 0)
-            return 'unsupported';
-        return weighted.some(isReady) ? 'available' : 'unavailable';
+        return { status: weighted.some(isReady) ? 'available' : 'unavailable', eligible: weighted };
     }
     instanceSpotPlacementTypes() {
         const prefix = 'instance-spot-type:';

package/dist/runtime/host/actor-packet-relay.d.ts

@@ -43,7 +43,7 @@ export declare class ZLinkActorPacketRelay {
         readonly deferredResponse?: boolean;
         readonly actorPacketTarget?: unknown;
     }>;
-    relayActorPacket(actor: ZLinkSessionActor, frameHeader: ZLinkStreamFrameHeader, payload: Message, signal?: AbortSignal): Promise<boolean>;
+    relayActorPacket(actor: ZLinkSessionActor, frameHeader: ZLinkStreamFrameHeader, payload: Message): Promise<boolean>;
     confirmRemoteSessionBinding(actor: ActorRef, sessionNodeRid: RoutingId, sessionRid: RoutingId, signal?: AbortSignal, options?: ZLinkSessionBindingConfirmationOptions): Promise<void>;
     /**
      * Session–Actor binding §5·§6 (.NET ZLinkSessionActorCoordinator rule): a
@@ -51,7 +51,7 @@ export declare class ZLinkActorPacketRelay {
      * same install a remote command 38 uses, so relocation seals and carries it.
      */
     private installSameNodeSessionBinding;
-    relayRemoteActorPacket(actor: ZLinkSessionActor, frameHeader: ZLinkStreamFrameHeader, payload: Message, signal?: AbortSignal): Promise<boolean>;
+    relayRemoteActorPacket(actor: ZLinkSessionActor, frameHeader: ZLinkStreamFrameHeader, payload: Message): Promise<boolean>;
     notifyRemoteActorDisconnected(actorId: string, remoteTarget: ZLinkRemoteBoundSessionTarget | ZLinkRemoteActorPacketTarget, signal?: AbortSignal, bindingActorRef?: ActorRef): Promise<void>;
     private requireCurrentRemoteBinding;
     private requestRemoteTarget;