@zlink-systems/framework 0.29.0 → 0.30.0

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

@@ -1,4 +1,5 @@
 import type { ApplicationJobRecordLease } from '../application-jobs/application-ingress-record-owner';
+import type { ReceiveRecord } from './service-runtime-contracts';
 export type ServiceMailboxDomain = 'application' | 'infrastructure';
 export interface ServiceMailboxRecord {
     readonly owner: string;
@@ -17,6 +18,8 @@ export interface ServiceMailboxRecord {
     readonly stateful?: unknown;
     /** Host queue permit plus its ordinary Framework-owned ingress record. */
     readonly applicationJob?: ApplicationJobRecordLease;
+    /** Unregistered raw-pull terminal, retained by the existing mailbox owner. */
+    readonly completion?: ReceiveRecord;
 }
 export interface ServiceMailboxClaim {
     readonly owner: string;

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

@@ -24,7 +24,8 @@ class ServiceMailbox {
         record.parts = [];
     }
     tryEnqueue(record) {
-        if (record.owner.length === 0 || record.parts.length === 0) {
+        if (record.owner.length === 0 ||
+            (record.parts.length === 0 && record.completion === undefined)) {
             throw new TypeError('Mailbox records require an owner and retained payload.');
         }
         const target = this.domain(record.domain);

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

@@ -5,7 +5,7 @@ import type { ServiceInstanceActivationRecoveryEnvelope } from './service-instan
 import type { ServiceMailboxRecord } from './service-mailbox';
 import { type ReceiveKindData, type ServiceStreamSessionBinding, type StreamSessionActorAuthorityFence } from './service-runtime-contracts';
 import { ServiceStatefulRegistry, type ServiceActorRef, type ServiceActorState, type ServiceSessionBinding, type ServiceSpotRef, type ServiceSpotState } from './service-stateful-registry';
-import { type ServiceActorCreateRecord, type ServiceActorRouteFence, type ServiceDirectSpotRouteFence, type ServiceInstanceActivationTarget, type ServiceInstanceRouteFence, type ServiceRetiredBoundSessionRouteFence, type ServiceStatefulReplyTail, type ServiceStatefulWireRecord, type ServiceUserSpotCloseRecord, type ServiceUserSpotCreateRecord } from './service-stateful-wire-codec';
+import { type ServiceActorCreateRecord, type ServiceActorRouteFence, type ServiceDirectSpotRouteFence, type ServiceInstanceActivationTarget, type ServiceInstanceColdActivationTarget, type ServiceInstanceRouteFence, type ServiceRetiredBoundSessionRouteFence, type ServiceStatefulReplyTail, type ServiceStatefulWireRecord, type ServiceUserSpotCloseRecord, type ServiceUserSpotCreateRecord } from './service-stateful-wire-codec';
 import { type ServiceApplicationPayload } from './service-wire-m6a-codec';
 export interface ServiceSpotMessageFollowSeal {
     readonly key: string;
@@ -148,7 +148,7 @@ export interface ServiceInstanceActivationAuthority {
  * operation completes; the binding callback itself never blocks.
  */
 export interface ServiceAsyncInstanceActivationAuthority {
-    read(target: ServiceInstanceActivationTarget): Promise<ServiceInstanceAuthorityRead>;
+    read(target: ServiceInstanceActivationTarget, instanceIntent?: true, activation?: ServiceInstanceActivationRecoveryEnvelope, acceptsLocal?: (route: ServiceInstanceRouteFence) => boolean): Promise<ServiceInstanceAuthorityRead>;
     reserve(activation: Omit<ServiceInstanceActivationRecoveryEnvelope, 'targetMeshName'>, signal?: AbortSignal): Promise<ServiceInstanceAuthorityReserve>;
     resume(target: ServiceInstanceActivationTarget, pending: ServicePendingInstanceActivation): Promise<ServiceInstanceActivationReservation>;
     commit(target: ServiceInstanceActivationTarget, reservation: ServiceInstanceActivationReservation, spot: ServiceSpotState, deadlineUnixMs?: bigint): Promise<{
@@ -280,11 +280,11 @@ export declare class ServiceStatefulRuntime {
         readonly bindingGeneration: bigint;
     }): ServiceStatefulPendingOperation;
     sendToInstanceSpot(route: ServiceInstanceRouteFence, payload: ServiceApplicationPayload, sourceSpotId?: string, metadataFrame?: Uint8Array, instanceIntent?: boolean): Promise<number>;
-    sendToMissingInstanceSpot(target: ServiceInstanceActivationTarget, payload: ServiceApplicationPayload, deadlineUnixMs: bigint, sourceSpotId?: string, metadataFrame?: Uint8Array): Promise<number>;
-    sendToMissingInstanceSpotFrame(target: ServiceInstanceActivationTarget, payloadFrame: Buffer, deadlineUnixMs: bigint, sourceSpotId?: string, metadataFrame?: Uint8Array): Promise<number>;
+    sendToMissingInstanceSpot(target: ServiceInstanceColdActivationTarget, payload: ServiceApplicationPayload, deadlineUnixMs: bigint, sourceSpotId?: string, metadataFrame?: Uint8Array): Promise<number>;
+    sendToMissingInstanceSpotFrame(target: ServiceInstanceColdActivationTarget, payloadFrame: Buffer, deadlineUnixMs: bigint, sourceSpotId?: string, metadataFrame?: Uint8Array): Promise<number>;
     requestToInstanceSpot(route: ServiceInstanceRouteFence, payload: ServiceApplicationPayload, timeoutMs: number, sourceSpotId?: string, metadataFrame?: Uint8Array, instanceIntent?: boolean): ServiceStatefulPendingOperation;
-    requestToMissingInstanceSpot(target: ServiceInstanceActivationTarget, payload: ServiceApplicationPayload, timeoutMs: number, sourceSpotId?: string, metadataFrame?: Uint8Array): ServiceStatefulPendingOperation;
-    requestToMissingInstanceSpotFrame(target: ServiceInstanceActivationTarget, payloadFrame: Buffer, deadlineUnixMs: bigint, sourceSpotId?: string, metadataFrame?: Uint8Array): ServiceStatefulPendingOperation;
+    requestToMissingInstanceSpot(target: ServiceInstanceColdActivationTarget, payload: ServiceApplicationPayload, timeoutMs: number, sourceSpotId?: string, metadataFrame?: Uint8Array): ServiceStatefulPendingOperation;
+    requestToMissingInstanceSpotFrame(target: ServiceInstanceColdActivationTarget, payloadFrame: Buffer, deadlineUnixMs: bigint, sourceSpotId?: string, metadataFrame?: Uint8Array): ServiceStatefulPendingOperation;
     lookupRemoteActor(targetNodeRid: string, actorId: string, timeoutMs: number): ServiceStatefulPendingOperation;
     destroyActor(actor: ServiceActorRef, timeoutMs: number): ServiceStatefulPendingOperation;
     joinActor(actor: ServiceActorRef, targetNodeRid: string, targetSpot: ServiceSpotRef, targetSpotGeneration: bigint, payload: ServiceApplicationPayload | undefined, timeoutMs: number): ServiceStatefulPendingOperation;
@@ -324,6 +324,7 @@ export declare class ServiceStatefulRuntime {
     private requireReadyInstanceApplicationRoute;
     private validateInstanceIngress;
     private activateMissingInstance;
+    private localReadyInstance;
     private activateMissingInstanceAsync;
     private runMissingInstanceActivation;
     private acceptsLocalMissingInstancePlacement;

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

@@ -345,7 +345,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 +362,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
@@ -754,7 +754,7 @@ class ServiceStatefulRuntime {
         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: this.nodeGeneration, low: pending.id }, deadlineUnixMs, pending.id, metadataFrame !== undefined),
+            (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');
         return pending;
@@ -1436,14 +1436,15 @@ class ServiceStatefulRuntime {
     async continueMissingInstanceActivation(ingress, record, payloadFrame, localReply, metadataFrame) {
         try {
             this.validateInstanceIngress(ingress, record);
-            const activation = await this.activateMissingInstanceAsync(record, payloadFrame, metadataFrame);
-            if (this.closed)
-                return;
-            const terminal = this.activationTerminalCompletion(record.target, activation.route);
-            const admitted = this.enqueueActivatedInstanceSpot(ingress, record, payloadFrame, activation.spot, localReply, terminal.onTerminalCompletion, metadataFrame, terminal.onHandlerTurnStarted, this.instanceApplicationTarget(record, activation.route.objectGeneration));
-            if (admitted !== 'application') {
-                throw new Error('Activated Instance message was not admitted to the local queue.');
-            }
+            await this.activateMissingInstanceAsync(record, payloadFrame, metadataFrame, (activation) => {
+                if (this.closed)
+                    return;
+                const terminal = this.activationTerminalCompletion(record.target, activation.route);
+                const admitted = this.enqueueActivatedInstanceSpot(ingress, record, payloadFrame, activation.spot, localReply, terminal.onTerminalCompletion, metadataFrame, terminal.onHandlerTurnStarted, this.instanceApplicationTarget(record, activation.route.objectGeneration));
+                if (admitted !== 'application') {
+                    throw new Error('Activated Instance message was not admitted to the local queue.');
+                }
+            });
         }
         catch (error) {
             this.finishMissingInstanceActivationFailure(ingress, record, error, localReply);
@@ -1738,12 +1739,43 @@ class ServiceStatefulRuntime {
         }
         return activation.spot;
     }
-    activateMissingInstanceAsync(record, payloadFrame, metadataFrame) {
-        const key = instanceActivationKey(record);
+    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);
-        if (pending !== undefined)
-            return pending;
-        const activation = this.runMissingInstanceActivation(record, payloadFrame, metadataFrame);
+        const ready = pending ??
+            this.runMissingInstanceActivation(record, payloadFrame, metadataFrame).then((activation) => ({
+                ...activation,
+                stableType: record.target.stableType
+            }));
+        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.');
+            }
+            admit(value);
+            return value;
+        });
+        // The caller owns operation failure. Keep the activation available for later participants.
+        const activation = operation.then((value) => value, () => ready);
         this.pendingInstanceActivations.set(key, activation);
         const clear = () => {
             if (this.pendingInstanceActivations.get(key) === activation) {
@@ -1751,7 +1783,7 @@ class ServiceStatefulRuntime {
             }
         };
         void activation.then(clear, clear);
-        return activation;
+        return operation;
     }
     async runMissingInstanceActivation(record, payloadFrame, metadataFrame) {
         const target = record.target;
@@ -1764,8 +1796,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) {
@@ -1809,13 +1847,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);
         }
@@ -1852,18 +1886,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();
@@ -3855,10 +3878,6 @@ function instanceOperationKey(record) {
     return (`${record.sourceNodeRid}\0${record.sourceNodeGeneration}\0` +
         `${record.operation.high}\0${record.operation.low}`);
 }
-function instanceActivationKey(record) {
-    return (`${record.target.targetNodeRid}\0${record.target.targetNodeGeneration}\0` +
-        `${record.target.targetSpotId}\0${record.target.stableType}`);
-}
 function subscriptionKey(channelName, topicFilter) {
     if (channelName.length === 0 || topicFilter.length === 0) {
         throw new TypeError('Channel name and topic filter must be non-empty.');

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

@@ -320,6 +320,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 +478,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 +552,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 {
@@ -25,7 +26,8 @@ export interface ServiceNodeDescriptor {
 }
 export interface AdmittedServicePeer {
     readonly descriptor: ServiceNodeDescriptor;
-    readonly connectionId: string;
+    readonly connectionId: string | bigint;
+    readonly liveness?: ServiceLivenessConnection;
 }
 export interface ServicePeerAdmissionExpectation {
     readonly endpoint?: string;
@@ -44,8 +46,8 @@ 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): PeerAdmissionResult;
+    disconnect(nodeRoutingId: string, connectionId: string | bigint): boolean;
     peer(nodeRoutingId: string): AdmittedServicePeer | undefined;
     peers(): readonly AdmittedServicePeer[];
     private peersCore;

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

@@ -41,10 +41,13 @@ class ServiceTopologyRegistry {
         }
         this.rebuildSelections();
     }
-    admit(descriptor, connectionId, expected) {
+    admit(descriptor, connectionId, expected, admitLiveness) {
         try {
             validateDescriptor(descriptor);
-            requireText(connectionId, 'connectionId');
+            if (typeof connectionId === 'string')
+                requireText(connectionId, 'connectionId');
+            else if (connectionId === 0n)
+                throw new TypeError('connectionId must be nonzero.');
         }
         catch (error) {
             return 'invalidDescriptor';
@@ -86,7 +89,8 @@ class ServiceTopologyRegistry {
         // that route replaces the admission of a route it replaced.
         this.peersByRid.set(descriptor.nodeRoutingId, {
             descriptor: cloneDescriptor(descriptor),
-            connectionId
+            connectionId,
+            liveness: admitLiveness?.() ?? current?.liveness
         });
         this.remember(descriptor);
         this.rebuildSelections();
@@ -329,7 +333,8 @@ function cloneDescriptor(descriptor) {
 function clonePeer(peer) {
     return {
         descriptor: cloneDescriptor(peer.descriptor),
-        connectionId: peer.connectionId
+        connectionId: peer.connectionId,
+        liveness: peer.liveness
     };
 }
 function sameServiceNodeDescriptor(left, right) {

package/dist/runtime/handlers/handler-instance-scope.js

@@ -158,7 +158,7 @@ class LifecycleHandlerInstanceScope {
         }
     }
     async dispose(detachedTaskRunner) {
-        const disposeFromActiveInvocation = activeLifecycleScope.getStore() === this;
+        const disposeFromActiveInvocation = this.activeInvocations > 0 && activeLifecycleScope.getStore() === this;
         const disposal = this.beginDisposeCore();
         if (disposal.deferred !== undefined) {
             startOutsideLifecycleInvocation(() => {

package/dist/runtime/host/actor-packet-relay.js

@@ -173,8 +173,8 @@ class ZLinkActorPacketRelay {
             const state = this.options.actorManager()?.getState(relay.actorId);
             if (frameHeader.kind === protocol_1.ZLinkStreamMessageKind.Send) {
                 const dispatch = state?.spotId === undefined
-                    ? this.requireSpotNodeRuntime().dispatchEntryActorPacket(relay.actorId, [header, body], false, remoteBoundSessionTarget, fallbackActorRef)
-                    : this.requireSpotManager().dispatchRoutedActorPacket(state.spotId, relay.actorId, [header, body], false, remoteBoundSessionTarget, fallbackActorRef);
+                    ? this.requireSpotNodeRuntime().dispatchEntryActorPacket('remote', relay.actorId, [header, body], false, remoteBoundSessionTarget, fallbackActorRef)
+                    : this.requireSpotManager().dispatchRoutedActorPacket('remote', state.spotId, relay.actorId, [header, body], false, remoteBoundSessionTarget, fallbackActorRef);
                 // Spec 05 §1.3: a one-way Session Actor relay completes at relay
                 // queue admission, not after the remote application turn. In
                 // particular, a handler may register a deferred Join whose relocation
@@ -207,8 +207,8 @@ class ZLinkActorPacketRelay {
                 frameHeader.requestSeq !== undefined &&
                 relay.returnResponse !== true) {
                 const dispatch = state?.spotId === undefined
-                    ? this.requireSpotNodeRuntime().dispatchEntryActorPacket(relay.actorId, [header, body], false, remoteBoundSessionTarget, fallbackActorRef)
-                    : this.requireSpotManager().dispatchRoutedActorPacket(state.spotId, relay.actorId, [header, body], false, remoteBoundSessionTarget, fallbackActorRef);
+                    ? this.requireSpotNodeRuntime().dispatchEntryActorPacket('remote', relay.actorId, [header, body], false, remoteBoundSessionTarget, fallbackActorRef)
+                    : this.requireSpotManager().dispatchRoutedActorPacket('remote', state.spotId, relay.actorId, [header, body], false, remoteBoundSessionTarget, fallbackActorRef);
                 closeFrameMessages = false;
                 const deferredPacketName = frameHeader.name;
                 const deferredRequestSeq = frameHeader.requestSeq;
@@ -249,8 +249,8 @@ class ZLinkActorPacketRelay {
                 };
             }
             const response = state?.spotId === undefined
-                ? await this.requireSpotNodeRuntime().dispatchEntryActorPacket(relay.actorId, [header, body], relay.returnResponse === true, remoteBoundSessionTarget, fallbackActorRef)
-                : await this.requireSpotManager().dispatchRoutedActorPacket(state.spotId, relay.actorId, [header, body], relay.returnResponse === true, remoteBoundSessionTarget, fallbackActorRef);
+                ? await this.requireSpotNodeRuntime().dispatchEntryActorPacket('remote', relay.actorId, [header, body], relay.returnResponse === true, remoteBoundSessionTarget, fallbackActorRef)
+                : await this.requireSpotManager().dispatchRoutedActorPacket('remote', state.spotId, relay.actorId, [header, body], relay.returnResponse === true, remoteBoundSessionTarget, fallbackActorRef);
             return {
                 ok: true,
                 response,
@@ -551,7 +551,7 @@ class ZLinkActorPacketRelay {
         try {
             this.options.detachedTaskRunner.runDetached('local actor packet relay', async () => {
                 try {
-                    const response = await this.requireSpotManager().dispatchRoutedActorPacket(spotId, actor.actorId, [header, body], returnResponse);
+                    const response = await this.requireSpotManager().dispatchRoutedActorPacket('local', spotId, actor.actorId, [header, body], returnResponse);
                     if (!returnResponse) {
                         return;
                     }

package/dist/runtime/host/actor-placement-coordinator.d.ts

@@ -1,5 +1,5 @@
 import type { ActorRef, RoutingId, ZLinkActorCreateResult } from '../../contracts';
-import type { ZLinkAuthoritySnapshot, ZLinkLocationOwnerToken } from '../locations/internal-location-contracts';
+import type { ZLinkAuthoritySnapshot, ZLinkLocationOwnerToken, ZLinkObjectReserveRequest } from '../locations/internal-location-contracts';
 import type { ZLinkAuthorityStore, ZLinkObjectCreationStore } from '../locations/internal-store-contracts';
 import type { ServiceActorCreateRecord } from '../foundation/service-stateful-wire-codec';
 import type { ServiceUserSpotOperationResult } from '../foundation/service-stateful-runtime';
@@ -14,6 +14,7 @@ export interface ZLinkActorPlacementTarget {
     readonly sourceNodeGeneration: bigint;
 }
 export interface ZLinkActorPlacementCoordinatorOptions {
+    readonly actorRelocationPolicy?: (meshName: string, stableType: string) => ZLinkObjectReserveRequest['actorRelocationPolicy'];
     readonly store: ZLinkObjectCreationStore & ZLinkAuthorityStore;
     readonly target: (meshName: string | undefined, stableType: string, signal?: AbortSignal, excludedNodeRids?: ReadonlySet<string>) => Promise<ZLinkActorPlacementTarget | undefined>;
     readonly remoteCreate: (meshName: string, targetNodeRid: string, request: Omit<ServiceActorCreateRecord, 'kind' | 'correlation'>, timeoutMs: number) => Promise<ServiceUserSpotOperationResult>;

package/dist/runtime/host/actor-placement-coordinator.js

@@ -61,7 +61,8 @@ class ZLinkActorPlacementCoordinator {
                     },
                     target: reservationTarget(target),
                     creatingPayload,
-                    capacity: { actors: 1, spots: 0 }
+                    capacity: { actors: 1, spots: 0 },
+                    actorRelocationPolicy: this.options.actorRelocationPolicy?.(target.meshName, stableType)
                 }, deadline.signal, BigInt(deadlineUnixMs));
                 const existing = existingActor(reserved, actorId, stableType);
                 if (existing !== undefined) {

package/dist/runtime/host/actor-runtime-options-factory.d.ts

@@ -15,6 +15,7 @@ import type { ZLinkRuntimeAdmissionGate } from '../admission';
 import type { ZLinkRemoteActorPacketTarget } from '../actors';
 import type { ZLinkActorJoinRelocation } from '../actors/actor-join-relocation';
 export interface ZLinkActorRuntimeOptionsFactoryOptions {
+    readonly terminateActorActivation: (actor: ZLinkActor, terminal: () => Promise<void>) => Promise<void>;
     readonly registration: ZLinkFrameworkRegistration;
     /** Message flow tracer, so a failed deferred Join records its cause on the flow. */
     readonly messageFlow?: () => import('../diagnostics/message-flow').ZLinkMessageFlowTracer | undefined;
@@ -61,7 +62,7 @@ export interface ZLinkActorRuntimeOptionsFactoryOptions {
 export declare class ZLinkActorRuntimeOptionsFactory {
     private readonly options;
     constructor(options: ZLinkActorRuntimeOptionsFactoryOptions);
-    createActorManagerOptions(): Pick<ZLinkActorManagerOptions, 'joinCoordinator' | 'actorMeshNameProvider' | 'actorLeaveSpot' | 'messageSerializers' | 'nativeActorNode' | 'nativeActorNodeProvider' | 'nativeActorCompletionTableProvider' | 'actorCreatedNodeRidProvider' | 'actorRefResolver' | 'actorCreatedNotifier' | 'actorDestroyedCleanup' | 'publishActorAuthority' | 'locationLifecycle' | 'boundSessionFactory' | 'actorTransferRegistry' | 'shutdownSignal' | 'metrics' | 'admission'>;
+    createActorManagerOptions(): Pick<ZLinkActorManagerOptions, 'joinCoordinator' | 'actorMeshNameProvider' | 'actorLeaveSpot' | 'messageSerializers' | 'nativeActorNode' | 'nativeActorNodeProvider' | 'nativeActorCompletionTableProvider' | 'actorCreatedNodeRidProvider' | 'actorRefResolver' | 'actorCreatedNotifier' | 'actorDestroyedCleanup' | 'terminateActorActivation' | 'publishActorAuthority' | 'locationLifecycle' | 'boundSessionFactory' | 'actorTransferRegistry' | 'shutdownSignal' | 'metrics' | 'admission'>;
     createActorClientOptions(): ConstructorParameters<typeof DefaultZLinkActorClient>[0];
     private actorBelongsToMesh;
 }

package/dist/runtime/host/actor-runtime-options-factory.js

@@ -13,6 +13,7 @@ class ZLinkActorRuntimeOptionsFactory {
     createActorManagerOptions() {
         const actorTransferRegistry = this.options.actorTransferRegistry;
         return {
+            terminateActorActivation: this.options.terminateActorActivation,
             actorMeshNameProvider: this.options.actorMeshName,
             actorLeaveSpot: (meshName, spotId, actor, signal) => {
                 const spotManager = this.options.spotManager();
@@ -150,7 +151,7 @@ class ZLinkActorRuntimeOptionsFactory {
                 this.options.actorHandoff.isKnownStale(actor),
             handoffCapture: (meshName, actorId, parts, returnResponse, actor, deadlineUnixMs) => this.actorBelongsToMesh(meshName, actorId) &&
                 !this.options.actorHandoff.isProvisional(actorId)
-                ? this.options.actorHandoff.capture(actorId, parts, returnResponse, undefined, actor, deadlineUnixMs)
+                ? this.options.actorHandoff.capture('local', actorId, parts, returnResponse, undefined, actor, deadlineUnixMs)
                 : undefined,
             sendErrorReporter: this.options.reportPostCommitError
         };