@zlink-systems/framework 0.31.0 → 0.32.1

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

@@ -11,6 +11,7 @@ exports.decodeChannelRequestHeader = decodeChannelRequestHeader;
 exports.encodeReplyHeader = encodeReplyHeader;
 exports.decodeReplyHeader = decodeReplyHeader;
 exports.encodeApplicationPayload = encodeApplicationPayload;
+exports.encodeOwnedApplicationPayload = encodeOwnedApplicationPayload;
 exports.encodeMultipartApplicationPayload = encodeMultipartApplicationPayload;
 exports.encodeMultipartPayload = encodeMultipartPayload;
 exports.decodeApplicationPayload = decodeApplicationPayload;
@@ -25,6 +26,7 @@ exports.encodeReject = encodeReject;
 exports.decodeReject = decodeReject;
 exports.decodeHeader = decodeHeader;
 const stream_wire_1 = require("@zlink-systems/stream-wire");
+const payload_slab_1 = require("../../contracts/Common/payload-slab");
 const EndpointNotation_1 = require("../../contracts/Configuration/EndpointNotation");
 const service_topology_registry_1 = require("./service-topology-registry");
 const service_wire_binary_primitives_1 = require("./service-wire-binary-primitives");
@@ -142,7 +144,14 @@ function decodeReplyHeader(frame) {
     return result;
 }
 function encodeApplicationPayload(payload) {
-    const result = allocateApplicationPayload(payload.packetName, payload.contentType, payload.payload.byteLength);
+    return encodeApplicationPayloadWith(payload, payload_slab_1.allocatePayloadBytes);
+}
+/** Encodes a retained internal application frame with its own backing store. */
+function encodeOwnedApplicationPayload(payload) {
+    return encodeApplicationPayloadWith(payload, allocateOwnedPayloadBytes);
+}
+function encodeApplicationPayloadWith(payload, allocate) {
+    const result = allocateApplicationPayload(payload.packetName, payload.contentType, payload.payload.byteLength, allocate);
     result.set(payload.payload, result.byteLength - payload.payload.byteLength);
     return result;
 }
@@ -153,7 +162,7 @@ function encodeApplicationPayload(payload) {
  */
 function encodeMultipartApplicationPayload(parts, packetName, contentType) {
     const multipartLength = multipartPayloadLength(parts);
-    const result = allocateApplicationPayload(packetName, contentType, multipartLength);
+    const result = allocateApplicationPayload(packetName, contentType, multipartLength, payload_slab_1.allocatePayloadBytes);
     writeMultipartPayload(result, result.byteLength - multipartLength, parts);
     return result;
 }
@@ -197,7 +206,7 @@ function writeMultipartPayload(result, offset, parts) {
         offset += length;
     }
 }
-function allocateApplicationPayload(packetName, contentType, payloadLength) {
+function allocateApplicationPayload(packetName, contentType, payloadLength, allocate) {
     const packetNameLength = (0, service_wire_binary_primitives_1.canonicalServiceWireTextLength)(packetName, 'packetName', service_wire_binary_primitives_1.SERVICE_WIRE_TEXT8_MAX_BYTES, fail);
     const contentTypeLength = (0, service_wire_binary_primitives_1.canonicalServiceWireTextLength)(contentType, 'contentType', service_wire_binary_primitives_1.SERVICE_WIRE_TEXT8_MAX_BYTES, fail);
     if (payloadLength > MAX_U32)
@@ -207,10 +216,8 @@ function allocateApplicationPayload(packetName, contentType, payloadLength) {
     const bodyLength = frameLength - prefixLength;
     if (bodyLength > MAX_U32)
         fail('Application payload body exceeds u32.');
-    // Both callers write every payload byte after these header fields, so the
-    // frame needs no zero fill and a small frame comes from the shared pool
-    // instead of its own backing store.
-    const result = Buffer.allocUnsafe(frameLength);
+    // Both callers write every payload byte after these header fields.
+    const result = allocate(frameLength);
     result[0] = exports.APPLICATION_PAYLOAD_VERSION;
     result.writeUInt32BE(bodyLength, 1);
     let offset = writeText8(result, prefixLength, packetName, packetNameLength);
@@ -218,6 +225,9 @@ function allocateApplicationPayload(packetName, contentType, payloadLength) {
     result.writeUInt32BE(payloadLength, offset);
     return result;
 }
+function allocateOwnedPayloadBytes(length) {
+    return Buffer.allocUnsafeSlow(length);
+}
 function decodeApplicationPayload(frame) {
     const decoded = decodeApplicationPayloadView(frame);
     return {

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

@@ -21,7 +21,7 @@ export interface ZLinkActorPlacementCoordinatorOptions {
     readonly decodeRemoteReply?: (payload: Uint8Array) => unknown;
 }
 export declare class ZLinkActorPlacementCoordinator {
-    private readonly options;
+    readonly options: ZLinkActorPlacementCoordinatorOptions;
     constructor(options: ZLinkActorPlacementCoordinatorOptions);
     create(actorId: string, stableType: string, createOnly: boolean, meshName: string | undefined, requestPayload: Uint8Array, timeoutMs: number, signal?: AbortSignal): Promise<ZLinkActorCreateResult>;
     handleRemoteCreate(record: ServiceActorCreateRecord, materialize: (requestPayload: Uint8Array, authority: ZLinkAuthoritySnapshot, signal: AbortSignal) => Promise<{

package/dist/runtime/host/actor-transfer-runtime.d.ts

@@ -90,8 +90,8 @@ export declare class ZLinkActorTransferRuntime {
     completeRelocationSourceLeave(actor: ZLinkActor, sourceSpotId: RoutingId | undefined, signal?: AbortSignal): Promise<void>;
     relayMaintenanceTerminal(actorId: string, packet: ZLinkActorHandoffPacket, result: ZLinkActorHandoffResult, sourceNodeRid: RoutingId, targetAuthorityOwnerGeneration?: bigint): ZLinkActorHandoffTerminalAck;
     relayCanonicalMaintenanceTerminal(operationId: string, replyRouteId: string, result: ZLinkActorHandoffResult, sourceNodeRid: RoutingId, targetAuthorityOwnerGeneration?: bigint): ZLinkActorHandoffTerminalAcceptance;
-    private sealBoundSessionRoute;
-    private abortBoundSessionRouteSeal;
+    sealBoundSessionRoute(actor: ZLinkActor, state: ZLinkActorRuntimeState, signal?: AbortSignal, relocation?: ServiceWireOperationId, relocationTarget?: Pick<ZLinkMeshNodeDescriptor, 'rid' | 'lifecycleGeneration'>): Promise<ZLinkRemoteBoundSessionTarget | undefined>;
+    abortBoundSessionRouteSeal(actor: ZLinkActor, state: ZLinkActorRuntimeState, target: ZLinkRemoteBoundSessionTarget): Promise<void>;
     private observeBoundSessionSealAbort;
     getOrCreateRoutedActor(actorId: string, actorType: string, actorRef?: ActorRef, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, actorCreateRequest?: Message, signal?: AbortSignal): Promise<{
         readonly actor: ZLinkActor;
@@ -120,6 +120,6 @@ export declare class ZLinkActorTransferRuntime {
     rollbackRoutedActor(actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
     actorEntryNodeRid(actor: ZLinkActor): RoutingId | undefined;
     private requireActorManager;
-    private publishBoundSessionOwnership;
+    publishBoundSessionOwnership(actorId: string, actorRef: ZLinkBackendActorRef, ownershipGeneration: bigint, target: ZLinkRemoteBoundSessionTarget | undefined, targetOwnerLeaseGeneration: bigint | undefined): Promise<void>;
 }
 export {};

package/dist/runtime/host/application-job-queue.d.ts

@@ -133,7 +133,7 @@ export declare class ApplicationJobQueue implements ApplicationJobQueuePort {
     private recordCompletedWait;
     private updateLocalWaiters;
     private logLocalBacklog;
-    private evaluatePressure;
+    evaluatePressure(): void;
     private pauseDurationAt;
     private cumulativePauseDurationAt;
 }

package/dist/runtime/host/index.d.ts

@@ -1,17 +1,33 @@
+import { RequestRuntime } from '../foundation/request-runtime';
 import { inspectRuntime } from '../internal-observation';
-import { type ZLinkClientServerRuntime, type ZLinkFanoutRuntime, type ZLinkFrameworkLifecycleOptions, type ZLinkFrameworkRelocationOptions, type ZLinkFrameworkRelocationResult, type ZLinkFrameworkRuntime, type ZLinkFrameworkRuntimeStatus, type ZLinkFrameworkTerminationResult, type ZLinkListenerKind, type ZLinkListenerStatus, type ZLinkMeshNodeDescriptor, type ZLinkMessageFlowControl, type ZLinkMessageFlowLogMode, type ZLinkObservedStatus, type ZLinkRouteMeshRuntime } from '../../contracts';
+import type { ApplicationJobOrigin } from '../application-jobs/contracts';
+import { type ZLinkClientServerRuntime, type ZLinkFanoutRuntime, type ZLinkFrameworkLifecycleOptions, type ZLinkFrameworkRelocationOptions, type ZLinkFrameworkRelocationResult, type ZLinkFrameworkRuntime, type ZLinkFrameworkRuntimeStatus, type ZLinkFrameworkTerminationResult, type ZLinkListenerKind, type ZLinkListenerStatus, type ZLinkMeshNodeDescriptor, type ZLinkMessageFlowControl, type ZLinkMessageFlowLogMode, type ZLinkObservedStatus, type ZLinkRouteMeshRuntime, ZLinkFrameworkRelocationReason, ZLinkFrameworkRuntimeState } from '../../contracts';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
 import { type ZLinkLocationRuntimeQuery } from '../../contracts/Locations';
 import { type DefaultZLinkActorManager, type ZLinkActorManagerOptions, DefaultZLinkActorClient } from '../actors';
-import { type ZLinkBackendContext, type ZLinkBackendMeshNode } from '../backend';
-import { DefaultZLinkChannelRuntimeOptions, ZLinkChannelRuntimeManager, ZLinkRuntimeRouteTransport } from '../channels';
+import { ZLinkRuntimeAdmissionGate, type ZLinkMeshDispatchAdmission } from '../admission';
+import { type ZLinkBackendAdapterFactory, type ZLinkBackendContext, type ZLinkBackendMeshNode } from '../backend';
+import { type ZLinkBackendMessageLike as MessageLike } from '../backend/runtime-values';
+import { DefaultZLinkChannelRuntimeOptions, ZLinkChannelRuntimeManager, ZLinkDispatchErrorReporter, ZLinkRuntimeRouteTransport, type ZLinkDispatchErrorSink } from '../channels';
 import type { ZLinkFrameworkRegistration } from '../configuration';
-import { type ZLinkRuntimeEventPublisher } from '../diagnostics';
+import { type ZLinkRuntimeEventPublisher, ZLinkRuntimeMetrics, type ZLinkRuntimeMetricMeshSnapshot } from '../diagnostics';
 import { ZLinkFrameworkExecutionState } from '../execution';
-import { type ZLinkStoreLocationResolvers } from '../locations';
-import { DefaultZLinkSpotManager, ZLinkRuntimeSpotPublisherTransport, type ZLinkDetachedTaskRunner, type ZLinkSpotManagerOptions } from '../spots';
+import { ZLinkListenerRecords } from '../foundation/listener-records';
+import { type ReadyRecord, type ReceiveRecord } from '../foundation/service-runtime-contracts';
+import type { ServiceMessageFollowRecord } from '../foundation/service-stateful-wire-codec';
+import { type ZLinkLocationRuntime, type ZLinkStoreLocationResolvers } from '../locations';
+import { ZLinkSubmitStatus } from '../messaging/submission-result';
+import { DefaultZLinkSpotManager, ZLinkRuntimeSpotPublisherTransport, ZLinkSpotNodeRuntimeManager, type ZLinkDetachedTaskRunner, type ZLinkSpotManagerOptions } from '../spots';
+import type { ZLinkSpotRouteResolver } from '../spots/spot-routing-internal';
 import { DefaultZLinkBoundSessionFactory, ZLinkStreamBindingRuntime } from '../streams';
+import { ZLinkActorPlacementCoordinator } from './actor-placement-coordinator';
+import { ApplicationJobQueue } from './application-job-queue';
+import { ZLinkBoundSessionRelay } from './bound-session-relay';
+import { ZLinkEntryActorRuntimeService } from './entry-actor-runtime';
+import { ZLinkLocationRuntimeOwner } from './location-runtime-owner';
+import { ZLinkRouteMeshRuntimeCoordinator } from './route-mesh-runtime';
 import { DefaultZLinkRouteMeshRuntimeOptions } from './route-mesh-runtime-options';
+import { ZLinkHostServiceRelocationRuntime } from './service-relocation-host-runtime';
 import { ZLinkHostSpotAddressTransport } from './spot-address-transport';
 export interface ZLinkFrameworkRuntimeLifecycle {
     readonly isStarted: boolean;
@@ -42,8 +58,8 @@ export declare class ZLinkFrameworkRuntimeHost implements ZLinkFrameworkRuntimeL
     }>;
     private readonly backendAdapterFactory;
     private readonly lifecycleSink?;
-    private executionState?;
-    private runtimeState;
+    executionState?: ZLinkFrameworkExecutionState;
+    runtimeState: ZLinkFrameworkRuntimeState;
     private runtimeStatus?;
     private readonly runtimeObservationSource;
     private runtimeDeadline?;
@@ -58,21 +74,21 @@ export declare class ZLinkFrameworkRuntimeHost implements ZLinkFrameworkRuntimeL
     private shutdownOperationStartedAt?;
     private relocationTargetApplicationVersion?;
     private readonly runtimeObservers;
-    private channelRuntime?;
-    private spotNodeRuntime?;
+    channelRuntime?: ZLinkChannelRuntimeManager;
+    spotNodeRuntime?: ZLinkSpotNodeRuntimeManager;
     private streamRuntime?;
     private statefulAuthorityRoutes?;
-    private readonly locationOwner;
+    readonly locationOwner: ZLinkLocationRuntimeOwner;
     private readonly meshRouters;
-    private readonly boundSessionRelay;
+    readonly boundSessionRelay: ZLinkBoundSessionRelay;
     private readonly actorHandoff;
     private readonly actorTransferRegistry;
     private readonly actorTransferRuntime;
     private readonly actorTransferAuthorityRuntime;
-    private readonly serviceRelocation;
-    private readonly entryActorRuntime;
+    readonly serviceRelocation: ZLinkHostServiceRelocationRuntime;
+    readonly entryActorRuntime: ZLinkEntryActorRuntimeService;
     private actorManager?;
-    private actorPlacement?;
+    actorPlacement?: ZLinkActorPlacementCoordinator;
     private spotManager?;
     private userSpotCoordinator?;
     private ownerLeaseRecoveryRuntime?;
@@ -81,17 +97,17 @@ export declare class ZLinkFrameworkRuntimeHost implements ZLinkFrameworkRuntimeL
     private readonly destroyedActorRefs;
     private readonly runtimeEventPublisher;
     private readonly metrics;
-    private readonly applicationJobQueue;
+    readonly applicationJobQueue: ApplicationJobQueue;
     private readonly capacityStatus;
     private readonly metricRegistrations;
-    private readonly admission;
+    readonly admission: ZLinkRuntimeAdmissionGate;
     private readonly activationAdmission;
     private cachedLocationSpotRouteResolver?;
     private actorClientLocationResolver?;
     private readonly messageFlowModeCell;
     private telemetryLease;
     private dispatchErrorReporters;
-    private readonly runtimeOrPreStartErrorSink;
+    readonly runtimeOrPreStartErrorSink: ZLinkDispatchErrorSink;
     private cachedDiagnosticsContext?;
     private readonly preStartErrorSink;
     readonly channelTransport: () => ZLinkChannelRuntimeManager | undefined;
@@ -108,7 +124,7 @@ export declare class ZLinkFrameworkRuntimeHost implements ZLinkFrameworkRuntimeL
     readonly clientServerRuntime: ZLinkClientServerRuntime;
     readonly fanoutRuntime: ZLinkFanoutRuntime;
     private readonly relocationStore?;
-    private readonly routeMeshCoordinator;
+    readonly routeMeshCoordinator: ZLinkRouteMeshRuntimeCoordinator;
     constructor(options: ZLinkFrameworkRuntimeHostOptions, internalOptions?: unknown);
     get isStarted(): boolean;
     get status(): ZLinkFrameworkRuntimeStatus;
@@ -148,17 +164,17 @@ export declare class ZLinkFrameworkRuntimeHost implements ZLinkFrameworkRuntimeL
     start(): Promise<void>;
     private startCore;
     stop(): Promise<void>;
-    private runtimeMetricMeshSnapshots;
+    runtimeMetricMeshSnapshots(): readonly ZLinkRuntimeMetricMeshSnapshot[];
     private stopCore;
-    private installOwnerLeaseRecoveryPublication;
-    private resumeOwnerLeaseOwnedWork;
-    private enterServing;
+    installOwnerLeaseRecoveryPublication(runtime: ZLinkLocationRuntime, spotNodeRuntime: ZLinkSpotNodeRuntimeManager, channelRuntime: ZLinkChannelRuntimeManager): void;
+    resumeOwnerLeaseOwnedWork(runtime: ZLinkLocationRuntime, spotNodeRuntime: ZLinkSpotNodeRuntimeManager, channelRuntime: ZLinkChannelRuntimeManager): Promise<void>;
+    enterServing(spotNodeRuntime: ZLinkSpotNodeRuntimeManager, signal: AbortSignal | undefined): Promise<void>;
     private publishOrStayPreparing;
-    private startStatefulAuthority;
+    startStatefulAuthority(locationStore: import('../locations/domain-store-contract').ZLinkDomainLocationStore, spotNodeRuntime: ZLinkSpotNodeRuntimeManager, signal: AbortSignal | undefined): Promise<void>;
     private createStatefulAuthorityRoutes;
     private requiresStatefulAuthorityRuntime;
     private installLocationBackedAuthorities;
-    private removeOwnerLeaseRecoveryPublication;
+    removeOwnerLeaseRecoveryPublication(): void;
     private ownerAdmissionOpen;
     onApplicationBootstrap(): Promise<void>;
     onApplicationShutdown(): Promise<void>;
@@ -167,10 +183,10 @@ export declare class ZLinkFrameworkRuntimeHost implements ZLinkFrameworkRuntimeL
     private publishMeshRetiring;
     private publishMeshServing;
     private publishMeshDraining;
-    private preflightAutomaticPeerReadiness;
+    preflightAutomaticPeerReadiness(deadlineAt: number, targetApplicationVersion: bigint): Promise<ZLinkFrameworkRelocationReason | undefined>;
     private hasLocalStatefulRelocationWork;
     private hasExactAutomaticPeerReadiness;
-    private publishHostRelocated;
+    publishHostRelocated(): Promise<void>;
     private publishHostDraining;
     private cleanupOwnerForDrain;
     private registerInstanceApplicationLifecycle;
@@ -183,24 +199,61 @@ export declare class ZLinkFrameworkRuntimeHost implements ZLinkFrameworkRuntimeL
     createPublicSpotManager(local: DefaultZLinkSpotManager): import('../../contracts').ZLinkSpotManager;
     private actorRuntimeOptionsFactory;
     private createChannelRuntimeOptions;
-    private createSpotNodeRuntimeOptions;
+    createSpotNodeRuntimeOptions(context: ZLinkBackendContext, dispatchErrors: ZLinkDispatchErrorReporter): {
+        admission: ZLinkRuntimeAdmissionGate;
+        errorSink: ZLinkDispatchErrorSink;
+        peerAdmissionSealed: (meshName: string) => boolean;
+        messageFollowReceiver: (record: ServiceMessageFollowRecord) => void;
+        meshRecordDispatcher: (meshName: string, owner: ReadyRecord, record: ReceiveRecord) => void | Promise<void>;
+        activationConcurrency: (meshName: string) => import("../activation-admission").ZLinkActivationConcurrency;
+        context: ZLinkBackendContext;
+        applicationJobQueue?: ApplicationJobQueue;
+        registration: ZLinkFrameworkRegistration;
+        messageSerializers?: ReadonlyMap<string, import("../../contracts").ZLinkMessageSerializer>;
+        providerResolver?: ZLinkProviderResolver;
+        metrics?: import("../diagnostics").ZLinkRuntimeMetrics;
+        spotRouterChannelIdForMesh?: (meshName: string) => string;
+        runtimeEventPublisher?: ZLinkRuntimeEventPublisher;
+        actorHandoffRuntime?: import("../spots/spot-runtime-ports").ZLinkSpotActorHandoffRuntime;
+        actorTransferRuntime?: import("../spots/spot-runtime-ports").ZLinkSpotActorTransferRuntime;
+        boundSessionRuntime?: import("../spots/spot-runtime-ports").ZLinkSpotBoundSessionRuntime;
+        detachedTaskRunner: ZLinkDetachedTaskRunner;
+        dispatchErrors?: ZLinkDispatchErrorReporter;
+        channelClient?: import("../../contracts").ZLinkChannelClient;
+        fanoutClient?: import("../../contracts").ZLinkFanoutClient;
+        spotPublisherClient?: import("../../contracts").ZLinkSpotPublisherClient;
+        routedTransport?: import("../spots").ZLinkSpotRoutedTransport;
+        requests?: RequestRuntime;
+        listenerRecords?: ZLinkListenerRecords;
+        primaryMeshName?: string;
+        backendAdapterFactory: ZLinkBackendAdapterFactory;
+        spotRouteResolver?: ZLinkSpotRouteResolver;
+        entryActorRuntime?: import("../spots/spot-runtime-ports").ZLinkEntryActorRuntime;
+        applicationJobReceiveFlowFailureSink?: (error: unknown) => void;
+    };
     private dispatchMeshNodeRecord;
     private dispatchMeshNodePayload;
     private completeFormalSourceLeave;
-    private dispatchMeshRecord;
+    dispatchMeshRecord(applicationJobOrigin: () => ApplicationJobOrigin, meshName: string, owner: ReadyRecord, record: ReceiveRecord, signal?: AbortSignal): void | Promise<void>;
     private admitMeshDispatch;
-    private dispatchMeshActorBinding;
-    private submitLocalMeshRoute;
-    private dispatchMeshSpotRecord;
-    private createDispatchErrorReporter;
+    dispatchMeshActorBinding(meshName: string, record: ReceiveRecord, signal?: AbortSignal): Promise<void>;
+    submitLocalMeshRoute(meshName: string, sourceNodeRid: string, parts: readonly MessageLike[]): {
+        readonly status: ZLinkSubmitStatus.Shutdown;
+    } | {
+        readonly status: ZLinkSubmitStatus.TargetNotFound;
+    } | {
+        readonly status: ZLinkSubmitStatus.Submitted;
+    };
+    dispatchMeshSpotRecord(meshName: string, owner: ReadyRecord, record: ReceiveRecord, admit?: ZLinkMeshDispatchAdmission): Promise<void>;
+    createDispatchErrorReporter(errorSink: ZLinkDispatchErrorSink): ZLinkDispatchErrorReporter;
     detachedTaskRunner(): ZLinkDetachedTaskRunner;
     private diagnosticsContext;
-    private flowCreationEnabled;
+    flowCreationEnabled(): boolean;
     private runLifecycle;
     requirePrimaryMeshNode(): ZLinkBackendMeshNode;
     private ensureLocationRuntime;
-    private createLocationSpotRouteResolver;
-    private createActorLocationResolver;
+    createLocationSpotRouteResolver(): ZLinkSpotRouteResolver | undefined;
+    createActorLocationResolver(): ZLinkStoreLocationResolvers | undefined;
 }
 export declare function hasUnsupportedManualTopology(registration: ZLinkFrameworkRegistration): boolean;
 export declare function hasExactPeerReadiness(descriptors: readonly ZLinkMeshNodeDescriptor[], local: {

package/dist/runtime/host/index.js

@@ -559,7 +559,7 @@ class ZLinkFrameworkRuntimeHost {
                 clear: () => this.boundSessionRelay.boundSessions.clearServiceWireSessionRelocations()
             },
             trackInstanceSpot: (input) => this.locationOwner.currentLifecycle?.trackInstanceSpot(input),
-            invalidateActorRoute: (actorId) => this.actorClientLocationResolver?.invalidateActorRoute(actorId),
+            observeActorAuthorityVersion: (actorId, storeVersion) => this.actorClientLocationResolver?.observeActorAuthorityVersion(actorId, storeVersion),
             reconcileStatefulAuthorityRoutes: (signal) => this.statefulAuthorityRoutes?.reconcile(signal) ?? Promise.resolve(),
             runtimeEventPublisher: this.runtimeEventPublisher,
             metrics: this.metrics,
@@ -1998,7 +1998,7 @@ class ZLinkFrameworkRuntimeHost {
                 if (entrySpotId === undefined) {
                     throw new ConfigurationException_1.ZLinkConfigurationException(`Actor '${actorRef.actorId}' authority requires its RouteMesh Entry Spot.`);
                 }
-                await (0, actors_1.publishInitialActorAuthority)(store, {
+                const authority = await (0, actors_1.publishInitialActorAuthority)(store, {
                     actorType,
                     actor: actorRef,
                     meshName,
@@ -2008,7 +2008,7 @@ class ZLinkFrameworkRuntimeHost {
                     spotGeneration: ownerNodeGeneration,
                     spotKind: contracts_2.ZLinkSpotKind.Entry
                 }, signal);
-                this.actorClientLocationResolver?.invalidateActorRoute(actorRef.actorId);
+                this.actorClientLocationResolver?.observeActorAuthorityVersion(actorRef.actorId, authority.storeVersion.value);
             },
             reportPostCommitError: (error) => this.runtimeOrPreStartErrorSink.reportRuntimeTaskException('post-commit actor binding', error),
             reportBoundSessionSendError: (error) => this.runtimeOrPreStartErrorSink.reportRuntimeTaskException('bound session one-way submit', error),
@@ -2260,8 +2260,7 @@ class ZLinkFrameworkRuntimeHost {
             replyBindingFailure(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale);
             return;
         }
-        replyBindingSuccess();
-        state.installBoundSessionBinding({
+        const incomingTarget = {
             ...target,
             sessionNodeRid: binding.sessionNodeRid,
             sessionRid: binding.sessionRid,
@@ -2269,8 +2268,79 @@ class ZLinkFrameworkRuntimeHost {
             sessionOwnerId: binding.sessionOwnerId,
             sessionOwnerLeaseGeneration: binding.sessionOwnerLeaseGeneration,
             bindingGeneration: binding.bindingGeneration
+        };
+        const currentBinding = state.boundSession;
+        const currentActor = state.actor;
+        if (currentBinding === undefined ||
+            currentActor?.onDuplicateBind === undefined ||
+            samePhysicalSession(currentBinding, incomingTarget)) {
+            state.installBoundSessionBinding(incomingTarget);
+            replyBindingSuccess();
+            return;
+        }
+        const spotManager = this.spotManager;
+        if (spotManager === undefined || state.meshName === undefined) {
+            replyBindingFailure(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale);
+            return;
+        }
+        let callbackStarted;
+        const started = new Promise((resolve) => {
+            callbackStarted = resolve;
         });
-        return Promise.resolve();
+        let callbackTimedOut = false;
+        let timeoutHandle;
+        const cancellation = new AbortController();
+        const callbackSignal = signal === undefined ? cancellation.signal : AbortSignal.any([signal, cancellation.signal]);
+        const turn = spotManager.executeActorTurn(state.meshName, state.actor?.context.spotId, state.actorId, async () => {
+            const current = state.boundSession;
+            const actor = state.actor;
+            const duplicateCallback = current !== undefined && !samePhysicalSession(current, incomingTarget)
+                ? actor?.onDuplicateBind
+                : undefined;
+            if (duplicateCallback === undefined || actor === undefined || current === undefined) {
+                state.installBoundSessionBinding(incomingTarget);
+                replyBindingSuccess();
+                return;
+            }
+            callbackStarted();
+            const decision = await duplicateCallback.call(actor, sessionBindingIdentity(current), sessionBindingIdentity(incomingTarget), callbackSignal);
+            if (callbackTimedOut)
+                return;
+            if (decision !== undefined && decision.length > 0) {
+                if (Buffer.byteLength(decision, 'utf8') > 0xffff) {
+                    throw new RangeError('Duplicate bind rejection message exceeds Text16 capacity.');
+                }
+                if (record.replyFailure?.(runtime_values_1.RequestResult.Rejected, 0, {
+                    kind: 'streamBindRejected',
+                    rejectionMessage: decision
+                }) !== runtime_values_1.SubmitResult.Ok) {
+                    throw new ConfigurationException_1.ZLinkConfigurationException(`MeshNode Actor binding target '${binding.actor.actorId}' rejection acknowledgement failed.`);
+                }
+                return;
+            }
+            state.installBoundSessionBinding(incomingTarget);
+            replyBindingSuccess();
+        });
+        const timeout = started.then(() => new Promise((resolve) => {
+            timeoutHandle = setTimeout(() => {
+                callbackTimedOut = true;
+                resolve('timedOut');
+            }, this.options.registration.sessionReplacementCallbackTimeoutMs);
+        }));
+        try {
+            const outcome = await Promise.race([turn.then(() => 'completed'), timeout]);
+            if (outcome === 'timedOut') {
+                cancellation.abort((0, abort_1.createDeadlineExceededError)('Duplicate bind callback timed out.'));
+                if (record.replyFailure?.(runtime_values_1.RequestResult.TimedOut, 0) !== runtime_values_1.SubmitResult.Ok) {
+                    throw new ConfigurationException_1.ZLinkConfigurationException(`MeshNode Actor binding target '${binding.actor.actorId}' timeout acknowledgement failed.`);
+                }
+                void turn.catch((error) => this.runtimeOrPreStartErrorSink.reportRuntimeTaskException(`duplicate bind callback '${binding.actor.actorId}'`, error));
+            }
+        }
+        finally {
+            if (timeoutHandle !== undefined)
+                clearTimeout(timeoutHandle);
+        }
     }
     submitLocalMeshRoute(meshName, sourceNodeRid, parts) {
         const state = this.executionState;
@@ -2332,7 +2402,8 @@ class ZLinkFrameworkRuntimeHost {
                 contentType: envelope.header.contentType,
                 sourceNodeRid: String(record.sourceNodeRid ?? ''),
                 metadata: (0, contracts_2.zlinkMessageMetadata)(envelope.header.metadata),
-                correlationId: envelope.header.correlationId ?? undefined
+                correlationId: envelope.header.correlationId ?? undefined,
+                receivedAt: record.receivedAt ?? new Date()
             };
             try {
                 const dispatch = async () => {
@@ -2452,6 +2523,29 @@ function hasUnsupportedManualTopology(registration) {
     }
     return false;
 }
+function samePhysicalSession(left, right) {
+    return (left.sessionNodeRid !== undefined &&
+        left.sessionRid !== undefined &&
+        left.sessionOwnerNodeGeneration !== undefined &&
+        right.sessionNodeRid !== undefined &&
+        right.sessionRid !== undefined &&
+        right.sessionOwnerNodeGeneration !== undefined &&
+        (0, routing_id_1.routingIdsEqual)(left.sessionNodeRid, right.sessionNodeRid) &&
+        left.sessionRid === right.sessionRid &&
+        left.sessionOwnerNodeGeneration === right.sessionOwnerNodeGeneration);
+}
+function sessionBindingIdentity(value) {
+    if (value.sessionNodeRid === undefined ||
+        value.sessionOwnerNodeGeneration === undefined ||
+        value.bindingGeneration === undefined) {
+        throw new ConfigurationException_1.ZLinkConfigurationException('Duplicate bind callback requires a complete identity.');
+    }
+    return {
+        sessionOwnerNodeRid: value.sessionNodeRid,
+        sessionOwnerNodeGeneration: value.sessionOwnerNodeGeneration,
+        bindingGeneration: value.bindingGeneration
+    };
+}
 function hasConfiguredLocationStore(registration) {
     return (registration.locations.useInMemoryStores || registration.locations.storeInstance !== undefined);
 }

package/dist/runtime/host/location-runtime-owner.d.ts

@@ -19,8 +19,8 @@ export interface ZLinkLocationRuntimeStopSnapshot {
 }
 export declare class ZLinkLocationRuntimeOwner {
     private readonly options;
-    private stores?;
-    private runtime?;
+    stores?: ZLinkLocationRuntimeStores;
+    runtime?: ZLinkLocationRuntime;
     private lifecycle?;
     private events?;
     private leaseTrackerState?;