@zlink-systems/framework 0.30.0 → 0.30.2

package/dist/runtime/streams/native-fallback-bound-session.js

@@ -1,14 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkNativeFallbackBoundSession = void 0;
+const Registration_1 = require("../../contracts/Configuration/Registration");
 const framework_errors_internal_1 = require("../framework-errors-internal");
 const contracts_1 = require("../../contracts");
 const submission_result_1 = require("../messaging/submission-result");
 const actors_1 = require("../actors");
 const actor_packet_relay_wire_1 = require("../actors/actor-packet-relay-wire");
 const bound_session_wire_1 = require("../actors/bound-session-wire");
-const actor_routed_json_request_1 = require("../actors/actor-routed-json-request");
-const protocol_1 = require("./protocol");
 const packet_name_1 = require("../messaging/packet-name");
 const flow_context_1 = require("../diagnostics/flow-context");
 class ZLinkNativeFallbackBoundSession {
@@ -20,40 +19,12 @@ class ZLinkNativeFallbackBoundSession {
         return new ZLinkNativeFallbackBoundSessionSendCall(this.options, message);
     }
     async disconnect(signal) {
-        const remoteTarget = this.options.remoteBoundSessionTargetProvider();
-        if (remoteTarget !== undefined) {
-            const spotKind = 'spotKind' in remoteTarget
-                ? remoteTarget.spotKind
-                : undefined;
-            const payload = (0, actor_packet_relay_wire_1.encodeRemoteActorPacketRelayPayload)({
-                actorId: this.options.actorId,
-                routerChannelId: remoteTarget.routerChannelId,
-                header: (0, protocol_1.encodeStreamHeader)(disconnectedFrameHeader()),
-                payload: Buffer.alloc(0)
-            });
-            const target = {
-                routerChannelId: remoteTarget.routerChannelId,
-                targetNodeRid: remoteTarget.targetNodeRid,
-                spotId: remoteTarget.spotId,
-                spotKind: spotKind ?? contracts_1.ZLinkSpotKind.Entry
-            };
-            if (await (0, actor_routed_json_request_1.tryRequestRoutedJson)(this.options.routedTransport, target, payload, {
-                timeoutMs: this.options.requestTimeoutMs,
-                signal
-            })) {
-                return;
-            }
-            await this.options.routedTransport.sendToSpot(target, payload, {
-                packetName: actors_1.ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET
-            });
-            return;
-        }
         const actorRef = this.options.actorRefProvider();
         const node = this.options.nativeActorNodeProvider();
         if (actorRef !== undefined &&
             node !== undefined &&
             currentBindingGeneration(actorRef) !== undefined) {
-            await this.options.runtime.disconnectNativeBoundSession(node, actorRef, signal);
+            await this.options.runtime.disconnectNativeBoundSession(node, actorRef, this.options.requestTimeoutMs ?? Registration_1.DEFAULT_REQUEST_TIMEOUT_MS, signal);
             return;
         }
         await this.options.runtime.disconnectBoundSession(this.options.actorId, signal);
@@ -96,30 +67,11 @@ class ZLinkNativeFallbackBoundSessionSendCall {
     async executeScoped(packetName) {
         const localActor = this.options.localActorProvider?.() === true;
         const remoteTarget = this.options.remoteBoundSessionTargetProvider();
-        let nativeAttempted = false;
-        if (localActor) {
-            const result = await this.options.runtime.submitLocalBoundSession(this.options.actorId, this.message, packetName, this.selectedMetadata);
-            if (result.status !== submission_result_1.ZLinkSubmitStatus.TargetNotFound) {
-                this.traceSubmitted(result, packetName);
-                return result;
-            }
-            // A local Actor with a concrete native owner has a direct binding path.
-            // Use that path before a routed transfer target. The transfer target is
-            // retained for actors whose current owner is remote or whose native
-            // binding is no longer available.
-            const actorRef = this.options.actorRefProvider();
-            const node = this.options.nativeActorNodeProvider();
-            const bindingGeneration = currentBindingGeneration(actorRef);
-            if (actorRef !== undefined && node !== undefined && bindingGeneration !== undefined) {
-                nativeAttempted = true;
-                const result = await this.options.runtime.sendNativeBoundSession(node, actorRef, this.message, packetName, this.selectedMetadata);
-                if (result.status !== submission_result_1.ZLinkSubmitStatus.TargetNotFound) {
-                    this.traceSubmitted(result, packetName);
-                    return result;
-                }
-                if (remoteTarget === undefined) {
-                    return result;
-                }
+        if (localActor || remoteTarget === undefined) {
+            const localResult = await this.options.runtime.submitLocalBoundSession(this.options.actorId, this.message, packetName, this.selectedMetadata);
+            if (localResult.status !== submission_result_1.ZLinkSubmitStatus.TargetNotFound) {
+                this.traceSubmitted(localResult, packetName);
+                return localResult;
             }
         }
         if (remoteTarget !== undefined) {
@@ -152,18 +104,10 @@ class ZLinkNativeFallbackBoundSessionSendCall {
             this.traceSubmitted(result, packetName);
             return result;
         }
-        const localResult = await this.options.runtime.submitLocalBoundSession(this.options.actorId, this.message, packetName, this.selectedMetadata);
-        if (localResult.status !== submission_result_1.ZLinkSubmitStatus.TargetNotFound) {
-            this.traceSubmitted(localResult, packetName);
-            return localResult;
-        }
         const actorRef = this.options.actorRefProvider();
         const node = this.options.nativeActorNodeProvider();
         const bindingGeneration = currentBindingGeneration(actorRef);
-        if (!nativeAttempted &&
-            actorRef !== undefined &&
-            node !== undefined &&
-            bindingGeneration !== undefined) {
+        if (actorRef !== undefined && node !== undefined && bindingGeneration !== undefined) {
             const result = await this.options.runtime.sendNativeBoundSession(node, actorRef, this.message, packetName, this.selectedMetadata);
             this.traceSubmitted(result, packetName);
             return result;
@@ -189,12 +133,3 @@ function currentBindingGeneration(actorRef) {
 function positiveBindingGeneration(generation) {
     return generation !== undefined && generation > 0n ? generation : undefined;
 }
-function disconnectedFrameHeader() {
-    return {
-        kind: protocol_1.ZLinkStreamMessageKind.Send,
-        codec: protocol_1.ZLinkStreamCodec.Raw,
-        flags: protocol_1.ZLinkStreamHeaderFlags.None,
-        name: actors_1.ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET,
-        metadata: new Map()
-    };
-}

package/dist/runtime/streams/session-actor-coordinator.d.ts

@@ -3,7 +3,7 @@ import type { ZLinkRuntimeMetrics } from '../diagnostics';
 import { ZLinkActorSessionBindingRegistry, type ZLinkActorSessionAuthorityFence } from './actor-session-binding-registry';
 import { ZLinkActorSessionLifecycleCoordinator } from './actor-session-lifecycle-coordinator';
 import { DefaultZLinkSessionActor, DefaultZLinkSessionContext } from './session-context';
-import type { ZLinkSessionBindingConfirmationOptions } from './stream-binding-runtime-ports';
+import type { ZLinkActorRouteCommitOptions, ZLinkSessionBindingConfirmationOptions } from './stream-binding-runtime-ports';
 export interface ZLinkSessionActorCoordinatorOptions {
     readonly actorBindTimeoutMs?: number;
     readonly actorRefResolver?: (actor: ZLinkActor) => ActorRef;
@@ -28,17 +28,11 @@ export declare class ZLinkSessionActorCoordinator {
     constructor(routes: ZLinkActorSessionBindingRegistry<DefaultZLinkSessionContext, DefaultZLinkSessionActor>, sessionActorRuntime: ConstructorParameters<typeof DefaultZLinkSessionActor>[0], options?: ZLinkSessionActorCoordinatorOptions, lifecycle?: ZLinkActorSessionLifecycleCoordinator);
     bind(context: DefaultZLinkSessionContext, actorOrRef: ZLinkActor | ActorRef, signal?: AbortSignal): Promise<DefaultZLinkSessionActor>;
     private replaceBinding;
-    private replaceBindingCore;
     private resolveAuthorityFence;
     bindOrGet(context: DefaultZLinkSessionContext, actorRef: ActorRef, signal?: AbortSignal): Promise<DefaultZLinkSessionActor>;
     rebindActor(actorRef: ActorRef, signal?: AbortSignal): Promise<void>;
     refreshActor(actorRef: ActorRef, signal?: AbortSignal): Promise<void>;
-    commitActorRoute(actorRef: ActorRef, signal?: AbortSignal, options?: {
-        readonly confirmRemoteSessionBinding?: boolean | 'send';
-        readonly releaseSeal?: {
-            readonly sealId: string;
-        };
-    }): Promise<void>;
+    commitActorRoute(actorRef: ActorRef, signal?: AbortSignal, options?: ZLinkActorRouteCommitOptions): Promise<void>;
     retireRemoteBinding(actorRef: ActorRef, sessionRid: ActorRef['nodeRid'], bindingGeneration: bigint, signal?: AbortSignal): Promise<boolean>;
     authorityFence(actorId: string): Promise<{
         readonly authorityOwnerGeneration: bigint;

package/dist/runtime/streams/session-actor-coordinator.js

@@ -26,10 +26,7 @@ class ZLinkSessionActorCoordinator {
             : this.resolveActorRef(actorOrRef);
         return await this.lifecycle.run(actorRef.actorId, async () => this.replaceBinding(context, actorRef, signal));
     }
-    async replaceBinding(context, actorRef, signal, confirmRemoteSessionBinding = true, releaseSeal) {
-        return await this.replaceBindingCore(context, actorRef, signal, confirmRemoteSessionBinding, releaseSeal);
-    }
-    async replaceBindingCore(context, actorRef, signal, confirmRemoteSessionBinding = true, releaseSeal) {
+    async replaceBinding(context, actorRef, signal) {
         (0, abort_1.throwIfAborted)(signal);
         if (actorRef.actorId.trim().length === 0) {
             throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound, 'Actor id must not be empty.');
@@ -60,22 +57,15 @@ class ZLinkSessionActorCoordinator {
             : undefined, previous?.actor.ref);
         const sessionActor = reuseActor ??
             new session_context_1.DefaultZLinkSessionActor(this.sessionActorRuntime, boundActorRef, bindingToken);
-        const sessionIdentity = String(this.actorBindingRoutingId(context));
+        const sessionIdentity = this.actorBindingRoutingId(context);
         if (previous === undefined) {
-            if (releaseSeal !== undefined) {
-                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorSessionNotBound, `Actor '${actorRef.actorId}' route switch has no Session binding to release.`, true);
-            }
             await this.routes.bind(context, sessionActor, bindingToken, authorityFence, sessionIdentity, () => sessionActor.updateRef(boundActorRef));
         }
-        else if (releaseSeal !== undefined) {
-            await this.routes.replaceAndReleaseSeal(previous, context, sessionActor, bindingToken, releaseSeal.sealId, authorityFence, sessionIdentity, () => sessionActor.updateRef(boundActorRef));
-        }
         else {
             await this.routes.replace(previous, context, sessionActor, bindingToken, authorityFence, sessionIdentity, () => sessionActor.updateRef(boundActorRef));
         }
-        if (confirmRemoteSessionBinding !== false &&
-            this.options.confirmRemoteActorSessionBinding !== undefined) {
-            const waitForAcknowledgement = previous === undefined && confirmRemoteSessionBinding !== 'send';
+        if (this.options.confirmRemoteActorSessionBinding !== undefined) {
+            const waitForAcknowledgement = previous === undefined;
             const confirmation = this.options.confirmRemoteActorSessionBinding(boundActorRef, this.actorBindingRoutingId(context), undefined, {
                 waitForAcknowledgement,
                 binding: context.stream instanceof managed_stream_1.ZLinkManagedStream
@@ -204,25 +194,18 @@ class ZLinkSessionActorCoordinator {
             if (route === undefined)
                 return;
             requireSameIncarnation(route.actor.ref, normalizedActorRef);
-            if ((0, routing_id_1.routingIdsEqual)(route.actor.ref.nodeRid, normalizedActorRef.nodeRid)) {
-                const authorityFence = await this.resolveAuthorityFence(normalizedActorRef, signal);
-                if (options.releaseSeal !== undefined &&
-                    !(await this.routes.validateSeal(normalizedActorRef.actorId, options.releaseSeal.sealId))) {
-                    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `Actor '${normalizedActorRef.actorId}' route switch did not match its relocation seal.`, true);
-                }
-                // A location refresh never changes the route's Session binding
-                // generation; the native bind owns it.
-                route.actor.updateRef(withBindingGeneration(normalizedActorRef, bindingGenerationOf(route.actor.ref), undefined));
-                if (authorityFence !== undefined) {
-                    await this.routes.updateAuthorityFence(normalizedActorRef.actorId, authorityFence);
-                }
-                if (options.releaseSeal !== undefined &&
-                    !(await this.routes.abortSeal(normalizedActorRef.actorId, options.releaseSeal.sealId))) {
-                    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `Actor '${normalizedActorRef.actorId}' route switch lost its relocation seal.`, true);
-                }
-                return;
+            const authorityFence = await this.resolveAuthorityFence(normalizedActorRef, signal);
+            // Relocation changes only the Actor route of this physical binding.
+            // Publish the ref and authority together in the binding registry's turn;
+            // a native bind would issue a different binding generation.
+            const boundActorRef = withBindingGeneration(normalizedActorRef, bindingGenerationOf(route.actor.ref), undefined);
+            const commitActor = () => route.actor.updateRef(boundActorRef);
+            if (options.releaseSeal !== undefined) {
+                await this.routes.replaceAndReleaseSeal(route, route.context, route.actor, route.bindingToken, options.releaseSeal.sealId, authorityFence, route.sessionIdentity, commitActor);
+            }
+            else {
+                await this.routes.replace(route, route.context, route.actor, route.bindingToken, authorityFence, route.sessionIdentity, commitActor);
             }
-            await this.replaceBinding(route.context, normalizedActorRef, signal, options.confirmRemoteSessionBinding, options.releaseSeal);
         });
     }
     async retireRemoteBinding(actorRef, sessionRid, bindingGeneration, signal) {

package/dist/runtime/streams/stream-binding-runtime-ports.d.ts

@@ -26,15 +26,8 @@ export interface ZLinkStreamActorLifecyclePort {
 }
 export interface ZLinkActorRouteCommitOptions {
     /**
-     * Relocation already carries the binding identity to the target actor. The
-     * follow-up confirmation can use a one-way route submission because a
-     * request/ACK would create a nested route request while the Session
-     * ownership command is being dispatched.
-     */
-    readonly confirmRemoteSessionBinding?: boolean | 'send';
-    /**
-     * Command 44 keeps ingress sealed while the native route is prepared, then
-     * publishes the new route and releases this exact seal in one owner turn.
+     * Command 44 publishes the Actor route of the existing binding and releases
+     * this exact seal in one owner turn.
      */
     readonly releaseSeal?: {
         readonly sealId: string;
@@ -68,7 +61,7 @@ export interface ZLinkRemoteBoundSessionPort extends ZLinkStreamActorLifecyclePo
     sendNativeBoundSessionError(node: ZLinkBackendActorSessionNode, actorRef: ActorRef, packetName: string, requestSeq: bigint, error: unknown, metadata: ReadonlyMap<string, string>, signal?: AbortSignal): Promise<void>;
 }
 export interface ZLinkNativeFallbackBoundSessionPort {
-    disconnectNativeBoundSession(node: ZLinkBackendActorSessionNode, actorRef: ActorRef, signal?: AbortSignal): Promise<void>;
+    disconnectNativeBoundSession(node: ZLinkBackendActorSessionNode, actorRef: ActorRef, timeoutMs: number, signal?: AbortSignal): Promise<void>;
     disconnectBoundSession(actorId: string, signal?: AbortSignal): Promise<void>;
     sendLocalBoundSession(actorId: string, message: unknown, packetName: string | undefined, metadata: ReadonlyMap<string, string>): Promise<boolean>;
     submitLocalBoundSession(actorId: string, message: unknown, packetName: string | undefined, metadata: ReadonlyMap<string, string>, signal?: AbortSignal): Promise<ZLinkSubmitResult>;

package/dist/runtime/streams/stream-session-runtime.d.ts

@@ -134,7 +134,7 @@ export declare class ZLinkStreamSessionNodeRuntime {
     private readonly receiveAbortController;
     private receiveLoop;
     private monitorLoop;
-    private readonly receiveWake;
+    private receiveWake;
     private receiveWorkSinceYield;
     constructor(options: ZLinkStreamSessionNodeRuntimeOptions & ZLinkStreamLivenessOptions);
     start(): void;

package/dist/runtime/streams/stream-session-runtime.js

@@ -33,27 +33,6 @@ const systemLivenessClock = {
     setTimer: (callback, delayMs) => setTimeout(callback, Math.min(delayMs, MAX_TIMER_DELAY_MS)),
     clearTimer: (timer) => clearTimeout(timer)
 };
-class ZLinkStreamReceiveWake {
-    pending;
-    resolvePending;
-    finish = () => {
-        const resolve = this.resolvePending;
-        this.pending = undefined;
-        this.resolvePending = undefined;
-        resolve?.();
-    };
-    wait() {
-        if (this.pending !== undefined)
-            return this.pending;
-        this.pending = new Promise((resolve) => {
-            this.resolvePending = resolve;
-        });
-        return this.pending;
-    }
-    wake() {
-        this.finish();
-    }
-}
 class ZLinkStreamSessionRuntime {
     options;
     removeSession;
@@ -87,7 +66,7 @@ class ZLinkStreamSessionRuntime {
             this.traceFrameWritten(kind, packetName, correlationId);
         });
         const sessionOrPromise = options.sessionFactory(this.context);
-        this.sessionReady = isPromiseLike(sessionOrPromise)
+        this.sessionReady = (0, abort_1.isPromiseLike)(sessionOrPromise)
             ? sessionOrPromise.then((session) => this.completeSessionCreation(session), (error) => {
                 this.context.completeConfiguration();
                 throw error;
@@ -650,7 +629,7 @@ class ZLinkStreamSessionNodeRuntime {
     receiveAbortController = new AbortController();
     receiveLoop;
     monitorLoop;
-    receiveWake = new ZLinkStreamReceiveWake();
+    receiveWake;
     receiveWorkSinceYield = 0;
     constructor(options) {
         this.options = options;
@@ -1113,13 +1092,20 @@ class ZLinkStreamSessionNodeRuntime {
         });
     }
     async waitReceiveLoopWake(signal) {
-        await Promise.race([
-            this.options.readablePoller.waitForReadable(signal),
-            this.receiveWake.wait()
-        ]);
+        const wake = new AbortController();
+        this.receiveWake = wake;
+        try {
+            // Readiness, internal wake and shutdown share one cancellable wait;
+            // no losing Promise retains reactions across receive cycles.
+            await this.options.readablePoller.waitForReadable(AbortSignal.any([signal, wake.signal]));
+        }
+        finally {
+            wake.abort();
+            this.receiveWake = undefined;
+        }
     }
     wakeReceiveLoop() {
-        this.receiveWake.wake();
+        this.receiveWake?.abort();
     }
     getOrCreateSession(routingId) {
         const sessionId = (0, managed_stream_1.streamSessionIdFromRoutingId)(routingId);
@@ -1153,9 +1139,6 @@ function streamMonitorHasEndpoint(event) {
     const endpoint = event;
     return endpoint.localAddr !== undefined || endpoint.remoteAddr !== undefined;
 }
-function isPromiseLike(value) {
-    return typeof value.then === 'function';
-}
 function normalizeStreamCloseReason(reason) {
     switch (reason) {
         case 'client_close':

package/dist/runtime/workers/index.js

@@ -409,7 +409,7 @@ class DefaultZLinkWorkerCall {
     yield(signal) {
         const turn = (0, execution_1.requireZLinkYieldTurn)(this.turn);
         const pending = this.begin(signal);
-        return turn.yieldPromise(pending);
+        return turn.yieldFrameworkPromise(pending);
     }
     begin(signal) {
         if (this.terminatorSelected) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zlink-systems/framework",
-  "version": "0.30.0",
+  "version": "0.30.2",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",
@@ -19,7 +19,7 @@
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/api-logs": "^0.221.0",
-    "@zlink-systems/stream-wire": "0.30.0",
-    "@zlink-systems/zlink": "1.19.0"
+    "@zlink-systems/stream-wire": "0.30.2",
+    "@zlink-systems/zlink": "1.20.0"
   }
 }

package/src/contracts/Actors/ZLinkActorClient.ts

@@ -1,4 +1,5 @@
 import type { ActorId } from '../Common';
+import type { ZLinkRequest } from '../Handlers/Attributes';
 
 export interface ZLinkActorClient {
   sendToActor(actorId: ActorId, message: unknown): ZLinkActorSendCall;
@@ -13,6 +14,6 @@ export interface ZLinkActorSendCall {
 export interface ZLinkActorRequestCall {
   metadata(key: string, value: string): this;
   timeout(timeoutMs: number): this;
-  submit<TReply>(signal?: AbortSignal): Promise<TReply>;
+  submit<TReply>(signal?: AbortSignal): ZLinkRequest<TReply>;
   yield<TReply>(signal?: AbortSignal): Promise<TReply>;
 }

package/src/contracts/Channels/Calls.ts

@@ -1,4 +1,5 @@
 import type { ZLinkMessageMetadata } from '../Common';
+import type { ZLinkRequest } from '../Handlers/Attributes';
 
 export interface ZLinkSendCall {
   metadata(key: string, value: string): this;
@@ -10,7 +11,7 @@ export interface ZLinkRequestCall {
   metadata(key: string, value: string): this;
   metadata(metadata: ZLinkMessageMetadata): this;
   timeout(timeoutMs: number): this;
-  submit<TReply>(signal?: AbortSignal): Promise<TReply>;
+  submit<TReply>(signal?: AbortSignal): ZLinkRequest<TReply>;
 }
 
 export interface ZLinkChannelRequestCall extends ZLinkRequestCall {

package/src/contracts/Common/ZLinkEncodedPayload.ts

@@ -1,18 +1,38 @@
-import { borrowEncodedPayload, storeEncodedPayload } from './encoded-payload-storage';
+import {
+  adoptEncodedPayload,
+  borrowEncodedPayload,
+  storeEncodedPayload
+} from './encoded-payload-storage';
 
 export class ZLinkEncodedPayload {
-  private constructor(bytes: Uint8Array) {
-    storeEncodedPayload(this, bytes);
+  private constructor(bytes: Uint8Array, owned: boolean) {
+    if (owned) {
+      adoptEncodedPayload(this, bytes);
+    } else {
+      storeEncodedPayload(this, bytes);
+    }
   }
 
+  /** Copies the supplied bytes. */
   static from(bytes: Uint8Array): ZLinkEncodedPayload {
-    return new ZLinkEncodedPayload(bytes);
+    return new ZLinkEncodedPayload(bytes, false);
+  }
+
+  /** Retains the supplied bytes without copying. Do not modify them afterward; mutation changes the payload. */
+  static fromOwned(bytes: Uint8Array): ZLinkEncodedPayload {
+    return new ZLinkEncodedPayload(bytes, true);
   }
 
+  /** Returns a copy of the stored bytes. */
   data(): Uint8Array {
     return new Uint8Array(this.stored());
   }
 
+  /** Returns the stored bytes without copying. Do not modify this view or its backing buffer. */
+  view(): Readonly<Uint8Array> {
+    return this.stored();
+  }
+
   toBytes(): Uint8Array {
     return this.data();
   }

package/src/contracts/Common/ZLinkMessageMetadata.ts

@@ -11,7 +11,7 @@ export interface ZLinkMessageMetadataPolicy {
 class ImmutableZLinkMessageMetadata implements ZLinkMessageMetadata {
   readonly values: ReadonlyMap<string, string>;
 
-  constructor(values: ReadonlyMap<string, string> | Readonly<Record<string, string>> = new Map()) {
+  constructor(values: Iterable<readonly [string, string]> = []) {
     this.values = Object.freeze(new ImmutableMetadataMap(values));
   }
 
@@ -23,12 +23,8 @@ class ImmutableZLinkMessageMetadata implements ZLinkMessageMetadata {
 class ImmutableMetadataMap implements ReadonlyMap<string, string> {
   readonly #values: Map<string, string>;
 
-  constructor(values: ReadonlyMap<string, string> | Readonly<Record<string, string>>) {
-    this.#values = new Map(
-      typeof (values as ReadonlyMap<string, string>)[Symbol.iterator] === 'function'
-        ? (values as ReadonlyMap<string, string>)
-        : Object.entries(values)
-    );
+  constructor(values: Iterable<readonly [string, string]>) {
+    this.#values = new Map(values);
   }
 
   get size(): number {
@@ -74,5 +70,14 @@ export const ZLinkMessageMetadataEmpty: ZLinkMessageMetadata = Object.freeze(
 export function zlinkMessageMetadata(
   values: ReadonlyMap<string, string> | Readonly<Record<string, string>>
 ): ZLinkMessageMetadata {
-  return Object.freeze(new ImmutableZLinkMessageMetadata(values));
+  const entries =
+    typeof (values as ReadonlyMap<string, string>)[Symbol.iterator] === 'function'
+      ? (values as ReadonlyMap<string, string>)
+      : Object.entries(values);
+  const size = Array.isArray(entries)
+    ? entries.length
+    : (entries as ReadonlyMap<string, string>).size;
+  return size === 0
+    ? ZLinkMessageMetadataEmpty
+    : Object.freeze(new ImmutableZLinkMessageMetadata(entries));
 }

package/src/contracts/Common/encoded-payload-storage.ts

@@ -6,9 +6,12 @@ export function storeEncodedPayload(owner: object, bytes: Uint8Array): Buffer {
   return stored;
 }
 
-export function adoptEncodedPayload(owner: object, bytes: Buffer): Buffer {
-  encodedPayloadStorage.set(owner, bytes);
-  return bytes;
+export function adoptEncodedPayload(owner: object, bytes: Uint8Array): Buffer {
+  const stored = Buffer.isBuffer(bytes)
+    ? bytes
+    : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  encodedPayloadStorage.set(owner, stored);
+  return stored;
 }
 
 export function borrowEncodedPayload(owner: object): Buffer | undefined {

package/src/contracts/Configuration/Builders.ts

@@ -141,7 +141,10 @@ export interface ZLinkMeshObjectRoleBuilder {
 export interface ZLinkMeshObjectClientBuilder {}
 
 export interface ZLinkMeshObjectServerBuilder {
-  addEntrySpot<TEntrySpot extends ZLinkEntrySpot>(entrySpotType: Type<TEntrySpot>): this;
+  addEntrySpot<TEntrySpot extends ZLinkEntrySpot>(
+    entrySpotType: Type<TEntrySpot>,
+    actorType: string
+  ): this;
   addSpotFactory<TSpot extends ZLinkSpot>(
     spotType: string,
     implementation: Type<TSpot>,

package/src/contracts/Configuration/RegistrationBuilderPolicy.ts

@@ -68,13 +68,18 @@ export function validateSessionReplacementCallbackTimeout(timeoutMs: number): nu
 }
 
 export function registerEntrySpot(
-  options: { entrySpotType?: Type<ZLinkEntrySpot> },
-  entrySpotType: Type<ZLinkEntrySpot>
+  options: { entrySpotType?: Type<ZLinkEntrySpot>; entrySpotActorType?: string },
+  entrySpotType: Type<ZLinkEntrySpot>,
+  actorType: string
 ): void {
   if (options.entrySpotType !== undefined) {
     throw new ZLinkConfigurationException('Duplicate Entry Spot registration on SpotNode.');
   }
+  if (typeof actorType !== 'string' || actorType.length === 0) {
+    throw new ZLinkConfigurationException('Entry Spot Actor type must be a non-empty string.');
+  }
   options.entrySpotType = entrySpotType;
+  options.entrySpotActorType = actorType;
 }
 
 export function registerSpotFactory(

package/src/contracts/Configuration/RegistrationBuilders.ts

@@ -1234,8 +1234,11 @@ class DefaultMeshObjectServerBuilder implements ZLinkMeshObjectServerBuilder {
     private readonly node: MutableSpotNodeOptions
   ) {}
 
-  addEntrySpot<TEntrySpot extends ZLinkEntrySpot>(entrySpotType: Type<TEntrySpot>): this {
-    registerEntrySpot(this.node, entrySpotType);
+  addEntrySpot<TEntrySpot extends ZLinkEntrySpot>(
+    entrySpotType: Type<TEntrySpot>,
+    actorType: string
+  ): this {
+    registerEntrySpot(this.node, entrySpotType, actorType);
     return this;
   }
 
@@ -1646,6 +1649,7 @@ interface MutableSpotNodeOptions {
   router?: MutableSpotRouterCapabilityOptions;
   pubSub?: MutableSpotPubSubCapabilityOptions;
   entrySpotType?: Type<ZLinkEntrySpot>;
+  entrySpotActorType?: string;
   spotFactories?: Type<ZLinkSpot>[];
   spotFactoryRegistrations?: Record<
     string,

package/src/contracts/Configuration/RegistrationTypes.ts

@@ -268,6 +268,7 @@ export interface ZLinkSpotNodeOptions {
   readonly router?: ZLinkSpotRouterCapabilityOptions;
   readonly pubSub?: ZLinkSpotPubSubCapabilityOptions;
   readonly entrySpotType?: Type<ZLinkEntrySpot>;
+  readonly entrySpotActorType?: string;
   readonly spotFactories?: readonly Type<ZLinkSpot>[];
   readonly spotFactoryRegistrations?: Readonly<
     Record<

package/src/contracts/Dispatch/ZLinkDispatchOptions.ts

@@ -85,7 +85,7 @@ export interface ZLinkRuntimeMessageFlowEvent {
   readonly commandId?: number;
   readonly messageSize?: number;
   readonly durationSeconds?: number;
-  readonly errorReason?: ZLinkDispatchErrorReason;
+  readonly errorReason?: ZLinkDispatchErrorReason | 'activation_timeout' | 'activation_rejected';
   readonly errorAction?: ZLinkDispatchErrorAction;
   readonly errorType?: string;
   readonly errorMessage?: string;
@@ -195,6 +195,7 @@ export type ZLinkDispatchErrorReason =
   | 'unexpected_reply'
   | 'backpressure'
   | 'target_closed'
+  | 'location_unavailable'
   | 'stale_target'
   | 'shutdown';
 

package/src/contracts/Handlers/Attributes.ts

@@ -4,23 +4,25 @@ import {
   type ZLinkPacketJsonContract
 } from './JsonContract';
 
-export const ZLINK_DECORATOR_METADATA = Symbol.for('@zlink-systems/framework:decorator');
-
-export interface ZLinkDecoratorMetadata {
-  readonly kind: string;
-  readonly packetName?: string;
-  readonly groupName?: string;
-  readonly methodName?: string;
-  readonly meshName?: string;
-  readonly channelName?: string;
-  readonly topic?: string;
-  readonly jsonContract?: ZLinkPacketJsonContract;
-}
+import {
+  ZLINK_DECORATOR_METADATA,
+  readZLinkDecoratorMetadata,
+  type ZLinkDecoratorMetadata
+} from '@zlink-systems/stream-wire/internal/json';
+export {
+  ZLINK_DECORATOR_METADATA,
+  readZLinkDecoratorMetadata
+} from '@zlink-systems/stream-wire/internal/json';
+export type { ZLinkDecoratorMetadata } from '@zlink-systems/stream-wire/internal/json';
 
 export function ZLinkHandlerGroup(groupName: string): ClassDecorator {
   return classDecorator({ kind: 'handlerGroup', groupName });
 }
 
+export interface ZLinkRequest<TReply> extends Promise<TReply> {
+  readonly admitted: Promise<void>;
+}
+
 export function ZLinkRequest(packetName?: string): MethodDecorator {
   return methodDecorator({ kind: 'request', packetName });
 }
@@ -106,12 +108,3 @@ function appendMetadata(target: object, metadata: ZLinkDecoratorMetadata): void
     writable: false
   });
 }
-
-export function readZLinkDecoratorMetadata(target: object): readonly ZLinkDecoratorMetadata[] {
-  if (!Object.prototype.hasOwnProperty.call(target, ZLINK_DECORATOR_METADATA)) {
-    return [];
-  }
-  return (target as Record<symbol, unknown>)[
-    ZLINK_DECORATOR_METADATA
-  ] as readonly ZLinkDecoratorMetadata[];
-}