ultravisor-beacon 0.0.7 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ultravisor-beacon",
-	"version": "0.0.7",
+	"version": "0.0.9",
 	"description": "Ultravisor Beacon: lightweight beacon client and Fable service for remote task execution",
 	"main": "source/Ultravisor-Beacon-Service.cjs",
 	"scripts": {

package/source/Ultravisor-Beacon-CapabilityManager.cjs

@@ -29,8 +29,14 @@ const libCapabilityAdapter = require('./Ultravisor-Beacon-CapabilityAdapter.cjs'
 
 class UltravisorBeaconCapabilityManager
 {
-	constructor()
+	constructor(pLog)
 	{
+		this.log = pLog || {
+			info: (...pArgs) => { console.log(...pArgs); },
+			warn: (...pArgs) => { console.warn(...pArgs); },
+			error: (...pArgs) => { console.error(...pArgs); }
+		};
+
 		// Map of Capability name -> descriptor
 		this._Capabilities = {};
 	}
@@ -45,13 +51,13 @@ class UltravisorBeaconCapabilityManager
 	{
 		if (!pDescriptor || !pDescriptor.Capability)
 		{
-			console.error('[CapabilityManager] Descriptor must have a Capability name.');
+			this.log.error('[CapabilityManager] Descriptor must have a Capability name.');
 			return false;
 		}
 
 		if (!pDescriptor.actions || Object.keys(pDescriptor.actions).length === 0)
 		{
-			console.warn(`[CapabilityManager] Capability "${pDescriptor.Capability}" has no actions.`);
+			this.log.warn(`[CapabilityManager] Capability "${pDescriptor.Capability}" has no actions.`);
 		}
 
 		this._Capabilities[pDescriptor.Capability] = pDescriptor;

package/source/Ultravisor-Beacon-Client.cjs

@@ -14,6 +14,10 @@
  */
 
 const libHTTP = require('http');
+const libOS = require('os');
+const libFS = require('fs');
+const libPath = require('path');
+const libCrypto = require('crypto');
 
 let libWebSocket;
 try
@@ -45,6 +49,15 @@ class UltravisorBeaconClient
 			Tags: {}
 		}, pConfig || {});
 
+		// Logger: use provided Fable log or fall back to console
+		this.log = this._Config.Log || {
+			trace: (...pArgs) => { console.log(...pArgs); },
+			debug: (...pArgs) => { console.log(...pArgs); },
+			info: (...pArgs) => { console.log(...pArgs); },
+			warn: (...pArgs) => { console.warn(...pArgs); },
+			error: (...pArgs) => { console.error(...pArgs); }
+		};
+
 		this._BeaconID = null;
 		this._PollInterval = null;
 		this._HeartbeatInterval = null;
@@ -52,13 +65,17 @@ class UltravisorBeaconClient
 		this._ActiveWorkItems = 0;
 		this._SessionCookie = null;
 		this._Authenticating = false;
+		this._ReconnectPending = false;
+		this._ReconnectAttempts = 0;
+		this._MaxReconnectDelayMs = 300000;
 
 		// WebSocket transport state — determined at runtime, not config
 		this._WebSocket = null;
 		this._UseWebSocket = false;
 
 		this._Executor = new libBeaconExecutor({
-			StagingPath: this._Config.StagingPath
+			StagingPath: this._Config.StagingPath,
+			Log: this.log
 		});
 
 		// Load capability providers
@@ -84,7 +101,7 @@ class UltravisorBeaconClient
 		}
 
 		let tmpCount = this._Executor.providerRegistry.loadProviders(tmpProviders);
-		console.log(`[Beacon] Loaded ${tmpCount} capability provider(s).`);
+		this.log.info(`[Beacon] Loaded ${tmpCount} capability provider(s).`);
 	}
 
 	// ================================================================
@@ -96,31 +113,31 @@ class UltravisorBeaconClient
 	 */
 	start(fCallback)
 	{
-		console.log(`[Beacon] Starting "${this._Config.Name}"...`);
-		console.log(`[Beacon] Server: ${this._Config.ServerURL}`);
+		this.log.info(`[Beacon] Starting "${this._Config.Name}"...`);
+		this.log.info(`[Beacon] Server: ${this._Config.ServerURL}`);
 
 		// Initialize all providers before registering
 		this._Executor.providerRegistry.initializeAll((pInitError) =>
 		{
 			if (pInitError)
 			{
-				console.error(`[Beacon] Provider initialization failed: ${pInitError.message}`);
+				this.log.error(`[Beacon] Provider initialization failed: ${pInitError.message}`);
 				return fCallback(pInitError);
 			}
 
 			let tmpCapabilities = this._Executor.providerRegistry.getCapabilities();
-			console.log(`[Beacon] Capabilities: ${tmpCapabilities.join(', ')}`);
+			this.log.info(`[Beacon] Capabilities: ${tmpCapabilities.join(', ')}`);
 
 			// Authenticate before registering (both transports need a session)
 			this._authenticate((pAuthError) =>
 			{
 				if (pAuthError)
 				{
-					console.error(`[Beacon] Authentication failed: ${pAuthError.message}`);
+					this.log.error(`[Beacon] Authentication failed: ${pAuthError.message}`);
 					return fCallback(pAuthError);
 				}
 
-				console.log(`[Beacon] Authenticated successfully.`);
+				this.log.info(`[Beacon] Authenticated successfully.`);
 
 				// Try WebSocket first — if ws library is available and the
 				// server supports it, we get push-based work dispatch.
@@ -131,7 +148,7 @@ class UltravisorBeaconClient
 					{
 						if (pWSError)
 						{
-							console.log(`[Beacon] WebSocket unavailable (${pWSError.message}), using HTTP polling.`);
+							this.log.info(`[Beacon] WebSocket unavailable (${pWSError.message}), using HTTP polling.`);
 							this._UseWebSocket = false;
 							this._startHTTP(fCallback);
 							return;
@@ -157,14 +174,14 @@ class UltravisorBeaconClient
 		{
 			if (pError)
 			{
-				console.error(`[Beacon] Registration failed: ${pError.message}`);
+				this.log.error(`[Beacon] Registration failed: ${pError.message}`);
 				return fCallback(pError);
 			}
 
 			this._BeaconID = pBeacon.BeaconID;
 			this._Running = true;
 
-			console.log(`[Beacon] Registered as ${this._BeaconID}`);
+			this.log.info(`[Beacon] Registered as ${this._BeaconID}`);
 
 			// Start polling for work
 			this._PollInterval = setInterval(() =>
@@ -190,7 +207,7 @@ class UltravisorBeaconClient
 	 */
 	stop(fCallback)
 	{
-		console.log(`[Beacon] Stopping...`);
+		this.log.info(`[Beacon] Stopping...`);
 		this._Running = false;
 
 		if (this._PollInterval)
@@ -226,7 +243,7 @@ class UltravisorBeaconClient
 		{
 			if (pShutdownError)
 			{
-				console.warn(`[Beacon] Provider shutdown warning: ${pShutdownError.message}`);
+				this.log.warn(`[Beacon] Provider shutdown warning: ${pShutdownError.message}`);
 			}
 
 			if (this._BeaconID)
@@ -235,15 +252,15 @@ class UltravisorBeaconClient
 				{
 					if (pError)
 					{
-						console.warn(`[Beacon] Deregistration warning: ${pError.message}`);
+						this.log.warn(`[Beacon] Deregistration warning: ${pError.message}`);
 					}
-					console.log(`[Beacon] Stopped.`);
+					this.log.info(`[Beacon] Stopped.`);
 					if (fCallback) return fCallback(null);
 				});
 			}
 			else
 			{
-				console.log(`[Beacon] Stopped.`);
+				this.log.info(`[Beacon] Stopped.`);
 				if (fCallback) return fCallback(null);
 			}
 		});
@@ -291,7 +308,7 @@ class UltravisorBeaconClient
 					// Take the name=value portion (before the first semicolon)
 					let tmpCookieParts = tmpSetCookieHeaders[0].split(';');
 					this._SessionCookie = tmpCookieParts[0].trim();
-					console.log(`[Beacon] Session cookie acquired.`);
+					this.log.info(`[Beacon] Session cookie acquired.`);
 				}
 
 				try
@@ -341,25 +358,25 @@ class UltravisorBeaconClient
 
 		this._SessionCookie = null;
 
-		console.log(`[Beacon] Reconnecting — re-authenticating...`);
+		this.log.info(`[Beacon] Reconnecting — re-authenticating...`);
 
 		this._authenticate((pAuthError) =>
 		{
 			if (pAuthError)
 			{
-				console.error(`[Beacon] Re-authentication failed: ${pAuthError.message}`);
+				this.log.error(`[Beacon] Re-authentication failed: ${pAuthError.message}`);
 				this._Authenticating = false;
 				setTimeout(() => { this._reconnect(); }, 10000);
 				return;
 			}
 
-			console.log(`[Beacon] Re-authenticated, re-registering...`);
+			this.log.info(`[Beacon] Re-authenticated, re-registering...`);
 
 			this._register((pRegError, pBeacon) =>
 			{
 				if (pRegError)
 				{
-					console.error(`[Beacon] Re-registration failed: ${pRegError.message}`);
+					this.log.error(`[Beacon] Re-registration failed: ${pRegError.message}`);
 					this._Authenticating = false;
 					setTimeout(() => { this._reconnect(); }, 10000);
 					return;
@@ -368,7 +385,7 @@ class UltravisorBeaconClient
 				this._BeaconID = pBeacon.BeaconID;
 				this._Authenticating = false;
 
-				console.log(`[Beacon] Reconnected as ${this._BeaconID}`);
+				this.log.info(`[Beacon] Reconnected as ${this._BeaconID}`);
 
 				// Restart polling
 				this._PollInterval = setInterval(() =>
@@ -420,9 +437,71 @@ class UltravisorBeaconClient
 			tmpBody.BindAddresses = this._Config.BindAddresses;
 		}
 
+		// Host identity — used by the reachability matrix to detect beacons that
+		// live on the same physical machine. Caller can override; default is the
+		// node hostname (which inside a container is the container ID).
+		tmpBody.HostID = this._Config.HostID || libOS.hostname();
+
+		// Shared filesystem mounts — each entry tells the coordinator about a
+		// local filesystem tree this beacon advertises as accessible. When two
+		// beacons report the same MountID, the reachability matrix can pick the
+		// "shared-fs" strategy to skip an HTTP file transfer entirely.
+		//
+		// The MountID derivation includes stat.dev so two beacons that bind-mount
+		// the same host directory get the same ID, while two unrelated /media
+		// directories on different machines get different IDs.
+		tmpBody.SharedMounts = this._normalizeSharedMounts(this._Config.SharedMounts);
+
 		this._httpRequest('POST', '/Beacon/Register', tmpBody, fCallback);
 	}
 
+	_normalizeSharedMounts(pMounts)
+	{
+		if (!Array.isArray(pMounts) || pMounts.length === 0)
+		{
+			return [];
+		}
+		let tmpResult = [];
+		for (let i = 0; i < pMounts.length; i++)
+		{
+			let tmpEntry = pMounts[i];
+			if (!tmpEntry || !tmpEntry.Root)
+			{
+				continue;
+			}
+			let tmpRoot;
+			try
+			{
+				tmpRoot = libPath.resolve(tmpEntry.Root);
+			}
+			catch (pError)
+			{
+				continue;
+			}
+			let tmpMountID = tmpEntry.MountID;
+			if (!tmpMountID)
+			{
+				try
+				{
+					let tmpStat = libFS.statSync(tmpRoot);
+					tmpMountID = libCrypto.createHash('sha256')
+						.update(tmpStat.dev + ':' + tmpRoot)
+						.digest('hex').substring(0, 16);
+				}
+				catch (pError)
+				{
+					// Mount root does not exist on this beacon — skip it.
+					continue;
+				}
+			}
+			tmpResult.push({
+				MountID: tmpMountID,
+				Root: tmpRoot
+			});
+		}
+		return tmpResult;
+	}
+
 	_deregister(fCallback)
 	{
 		this._httpRequest('DELETE', `/Beacon/${this._BeaconID}`, null, fCallback);
@@ -471,7 +550,7 @@ class UltravisorBeaconClient
 	_executeWorkItem(pWorkItem)
 	{
 		this._ActiveWorkItems++;
-		console.log(`[Beacon] Executing work item [${pWorkItem.WorkItemHash}] (${pWorkItem.Capability}/${pWorkItem.Action})`);
+		this.log.info(`[Beacon] Executing work item [${pWorkItem.WorkItemHash}] (${pWorkItem.Capability}/${pWorkItem.Action})`);
 
 		// Create a progress callback that sends updates to the server
 		let tmpWorkItemHash = pWorkItem.WorkItemHash;
@@ -493,7 +572,7 @@ class UltravisorBeaconClient
 
 			if (pError)
 			{
-				console.error(`[Beacon] Execution error for [${pWorkItem.WorkItemHash}]: ${pError.message}`);
+				this.log.error(`[Beacon] Execution error for [${pWorkItem.WorkItemHash}]: ${pError.message}`);
 				if (this._UseWebSocket)
 				{
 					this._wsReportError(pWorkItem.WorkItemHash, pError.message, []);
@@ -509,11 +588,11 @@ class UltravisorBeaconClient
 			let tmpOutputs = pResult.Outputs || {};
 			if (tmpOutputs.ExitCode && tmpOutputs.ExitCode !== 0)
 			{
-				console.warn(`[Beacon] Work item [${pWorkItem.WorkItemHash}] completed with exit code ${tmpOutputs.ExitCode}`);
+				this.log.warn(`[Beacon] Work item [${pWorkItem.WorkItemHash}] completed with exit code ${tmpOutputs.ExitCode}`);
 			}
 			else
 			{
-				console.log(`[Beacon] Work item [${pWorkItem.WorkItemHash}] completed successfully.`);
+				this.log.info(`[Beacon] Work item [${pWorkItem.WorkItemHash}] completed successfully.`);
 			}
 
 			// Upload output file if one was produced (Result is a local path)
@@ -529,7 +608,7 @@ class UltravisorBeaconClient
 					try
 					{
 						let tmpBuffer = tmpFS.readFileSync(tmpResultPath);
-						console.log(`[Beacon] Uploading result file ${tmpOutputFilename} (${tmpBuffer.length} bytes) for [${pWorkItem.WorkItemHash}]`);
+						this.log.info(`[Beacon] Uploading result file ${tmpOutputFilename} (${tmpBuffer.length} bytes) for [${pWorkItem.WorkItemHash}]`);
 						this._wsSend({
 							Action: 'WorkResultUpload',
 							WorkItemHash: pWorkItem.WorkItemHash,
@@ -540,7 +619,7 @@ class UltravisorBeaconClient
 					}
 					catch (pUploadError)
 					{
-						console.error(`[Beacon] Failed to upload result file: ${pUploadError.message}`);
+						this.log.error(`[Beacon] Failed to upload result file: ${pUploadError.message}`);
 					}
 				}
 			}
@@ -568,7 +647,7 @@ class UltravisorBeaconClient
 			{
 				if (pError)
 				{
-					console.error(`[Beacon] Failed to report completion for [${pWorkItemHash}]: ${pError.message}`);
+					this.log.error(`[Beacon] Failed to report completion for [${pWorkItemHash}]: ${pError.message}`);
 				}
 			});
 	}
@@ -581,7 +660,7 @@ class UltravisorBeaconClient
 			{
 				if (pError)
 				{
-					console.error(`[Beacon] Failed to report error for [${pWorkItemHash}]: ${pError.message}`);
+					this.log.error(`[Beacon] Failed to report error for [${pWorkItemHash}]: ${pError.message}`);
 				}
 			});
 	}
@@ -600,7 +679,7 @@ class UltravisorBeaconClient
 				if (pError)
 				{
 					// Fire-and-forget — log but don't affect execution
-					console.warn(`[Beacon] Failed to report progress for [${pWorkItemHash}]: ${pError.message}`);
+					this.log.warn(`[Beacon] Failed to report progress for [${pWorkItemHash}]: ${pError.message}`);
 				}
 			});
 	}
@@ -621,7 +700,7 @@ class UltravisorBeaconClient
 			{
 				if (pError)
 				{
-					console.warn(`[Beacon] Heartbeat failed: ${pError.message}`);
+					this.log.warn(`[Beacon] Heartbeat failed: ${pError.message}`);
 				}
 			});
 	}
@@ -730,7 +809,7 @@ class UltravisorBeaconClient
 
 		this._WebSocket.on('open', () =>
 		{
-			console.log(`[Beacon] WebSocket connected to ${tmpWSURL}`);
+			this.log.info(`[Beacon] WebSocket connected to ${tmpWSURL}`);
 
 			// Register over WebSocket
 			let tmpWSRegPayload = {
@@ -779,7 +858,7 @@ class UltravisorBeaconClient
 
 		this._WebSocket.on('error', (pError) =>
 		{
-			console.error(`[Beacon] WebSocket error: ${pError.message}`);
+			this.log.error(`[Beacon] WebSocket error: ${pError.message}`);
 			if (!tmpCallbackFired)
 			{
 				tmpCallbackFired = true;
@@ -789,13 +868,13 @@ class UltravisorBeaconClient
 
 		this._WebSocket.on('close', () =>
 		{
-			console.log(`[Beacon] WebSocket connection closed.`);
+			this.log.info(`[Beacon] WebSocket connection closed.`);
 			this._WebSocket = null;
 
-			if (this._Running && !this._Authenticating)
+			if (this._Running && !this._Authenticating && !this._ReconnectPending)
 			{
 				// Connection lost while running — attempt reconnect
-				this._wsReconnect();
+				this._scheduleReconnect();
 			}
 		});
 	}
@@ -821,7 +900,7 @@ class UltravisorBeaconClient
 		if (tmpData.EventType === 'BeaconRegistered')
 		{
 			this._BeaconID = tmpData.BeaconID;
-			console.log(`[Beacon] Registered via WebSocket as ${this._BeaconID}`);
+			this.log.info(`[Beacon] Registered via WebSocket as ${this._BeaconID}`);
 			if (typeof fRegistrationCallback === 'function')
 			{
 				fRegistrationCallback({ BeaconID: this._BeaconID });
@@ -831,14 +910,14 @@ class UltravisorBeaconClient
 		{
 			if (this._ActiveWorkItems >= this._Config.MaxConcurrent)
 			{
-				console.log(`[Beacon] At max concurrent capacity, ignoring pushed work item.`);
+				this.log.info(`[Beacon] At max concurrent capacity, ignoring pushed work item.`);
 				return;
 			}
 			this._executeWorkItem(tmpData.WorkItem);
 		}
 		else if (tmpData.EventType === 'Deregistered')
 		{
-			console.log(`[Beacon] Deregistered by server.`);
+			this.log.info(`[Beacon] Deregistered by server.`);
 			this._BeaconID = null;
 		}
 	}
@@ -932,6 +1011,34 @@ class UltravisorBeaconClient
 		}
 	}
 
+	/**
+	 * Schedule a reconnection with exponential backoff.
+	 * Prevents multiple close events from triggering parallel reconnections.
+	 */
+	_scheduleReconnect()
+	{
+		if (this._ReconnectPending || this._Authenticating)
+		{
+			return;
+		}
+
+		this._ReconnectPending = true;
+		this._ReconnectAttempts++;
+
+		// Exponential backoff: 10s, 20s, 40s, 80s, 160s, capped at 5 min
+		let tmpDelay = Math.min(
+			this._Config.ReconnectIntervalMs * Math.pow(2, this._ReconnectAttempts - 1),
+			this._MaxReconnectDelayMs);
+
+		this.log.info(`[Beacon] Scheduling reconnection attempt ${this._ReconnectAttempts} in ${Math.round(tmpDelay / 1000)}s`);
+
+		setTimeout(() =>
+		{
+			this._ReconnectPending = false;
+			this._wsReconnect();
+		}, tmpDelay);
+	}
+
 	/**
 	 * Reconnect the WebSocket after unexpected disconnection.
 	 * Falls back to HTTP polling if WebSocket can't be re-established.
@@ -951,15 +1058,15 @@ class UltravisorBeaconClient
 		}
 
 		this._SessionCookie = null;
-		console.log(`[Beacon] WebSocket disconnected — re-authenticating...`);
+		this.log.info(`[Beacon] Reconnecting — attempt ${this._ReconnectAttempts}...`);
 
 		this._authenticate((pAuthError) =>
 		{
 			if (pAuthError)
 			{
-				console.error(`[Beacon] Re-authentication failed: ${pAuthError.message}`);
+				this.log.error(`[Beacon] Re-authentication failed: ${pAuthError.message}`);
 				this._Authenticating = false;
-				setTimeout(() => { this._wsReconnect(); }, this._Config.ReconnectIntervalMs);
+				this._scheduleReconnect();
 				return;
 			}
 
@@ -971,21 +1078,23 @@ class UltravisorBeaconClient
 				if (pError)
 				{
 					// WebSocket failed — fall back to HTTP polling
-					console.log(`[Beacon] WebSocket reconnection failed, falling back to HTTP polling.`);
+					this.log.info(`[Beacon] WebSocket reconnection failed, falling back to HTTP polling.`);
 					this._UseWebSocket = false;
 					this._startHTTP((pHTTPError, pHTTPBeacon) =>
 					{
 						if (pHTTPError)
 						{
-							console.error(`[Beacon] HTTP fallback failed: ${pHTTPError.message}`);
-							setTimeout(() => { this._wsReconnect(); }, this._Config.ReconnectIntervalMs);
+							this.log.error(`[Beacon] HTTP fallback failed: ${pHTTPError.message}`);
+							this._scheduleReconnect();
 							return;
 						}
-						console.log(`[Beacon] Reconnected via HTTP polling as ${pHTTPBeacon.BeaconID}`);
+						this._ReconnectAttempts = 0;
+						this.log.info(`[Beacon] Reconnected via HTTP polling as ${pHTTPBeacon.BeaconID}`);
 					});
 					return;
 				}
-				console.log(`[Beacon] WebSocket reconnected as ${pBeacon.BeaconID}`);
+				this._ReconnectAttempts = 0;
+				this.log.info(`[Beacon] WebSocket reconnected as ${pBeacon.BeaconID}`);
 			});
 		});
 	}

package/source/Ultravisor-Beacon-Executor.cjs

@@ -24,7 +24,12 @@ class UltravisorBeaconExecutor
 	{
 		this._Config = pConfig || {};
 		this._StagingPath = this._Config.StagingPath || process.cwd();
-		this._ProviderRegistry = new libBeaconProviderRegistry();
+		this.log = this._Config.Log || {
+			info: (...pArgs) => { console.log(...pArgs); },
+			warn: (...pArgs) => { this.log.warn(...pArgs); },
+			error: (...pArgs) => { console.error(...pArgs); }
+		};
+		this._ProviderRegistry = new libBeaconProviderRegistry(this.log);
 	}
 
 	/**
@@ -432,7 +437,7 @@ class UltravisorBeaconExecutor
 		catch (pError)
 		{
 			// Best-effort cleanup
-			console.warn(`[Beacon Executor] Could not clean up work directory: ${pError.message}`);
+			this.log.warn(`[Beacon Executor] Could not clean up work directory: ${pError.message}`);
 		}
 	}
 
@@ -457,7 +462,7 @@ class UltravisorBeaconExecutor
 					}
 					catch (pError)
 					{
-						console.warn(`[Beacon Executor] Could not clean up affinity dir [${tmpEntries[i]}]: ${pError.message}`);
+						this.log.warn(`[Beacon Executor] Could not clean up affinity dir [${tmpEntries[i]}]: ${pError.message}`);
 					}
 				}
 			}

package/source/Ultravisor-Beacon-ProviderRegistry.cjs

@@ -15,8 +15,14 @@ const libPath = require('path');
 
 class UltravisorBeaconProviderRegistry
 {
-	constructor()
+	constructor(pLog)
 	{
+		this.log = pLog || {
+			info: (...pArgs) => { console.log(...pArgs); },
+			warn: (...pArgs) => { console.warn(...pArgs); },
+			error: (...pArgs) => { console.error(...pArgs); }
+		};
+
 		// Map of 'Capability:Action' → { provider, actionDef }
 		this._ActionHandlers = {};
 
@@ -40,7 +46,7 @@ class UltravisorBeaconProviderRegistry
 	{
 		if (!pProvider || !pProvider.Capability)
 		{
-			console.error('[ProviderRegistry] Provider must have a Capability.');
+			this.log.error('[ProviderRegistry] Provider must have a Capability.');
 			return false;
 		}
 
@@ -49,7 +55,7 @@ class UltravisorBeaconProviderRegistry
 
 		if (tmpActionNames.length === 0)
 		{
-			console.warn(`[ProviderRegistry] Provider "${pProvider.Name}" declares no actions.`);
+			this.log.warn(`[ProviderRegistry] Provider "${pProvider.Name}" declares no actions.`);
 		}
 
 		// Index each action by composite key
@@ -83,7 +89,7 @@ class UltravisorBeaconProviderRegistry
 
 		this._Providers[pProvider.Name] = pProvider;
 
-		console.log(`[ProviderRegistry] Registered "${pProvider.Name}" → ` +
+		this.log.info(`[ProviderRegistry] Registered "${pProvider.Name}" → ` +
 			`${pProvider.Capability} [${tmpActionNames.join(', ')}]`);
 
 		return true;
@@ -190,7 +196,7 @@ class UltravisorBeaconProviderRegistry
 
 		if (!tmpSource)
 		{
-			console.error('[ProviderRegistry] Provider descriptor must have a Source.');
+			this.log.error('[ProviderRegistry] Provider descriptor must have a Source.');
 			return false;
 		}
 
@@ -222,13 +228,13 @@ class UltravisorBeaconProviderRegistry
 		}
 		catch (pError)
 		{
-			console.error(`[ProviderRegistry] Failed to load provider from "${tmpSource}": ${pError.message}`);
+			this.log.error(`[ProviderRegistry] Failed to load provider from "${tmpSource}": ${pError.message}`);
 			return false;
 		}
 
 		if (!tmpProviderModule)
 		{
-			console.error(`[ProviderRegistry] Could not load provider from: ${tmpSource}`);
+			this.log.error(`[ProviderRegistry] Could not load provider from: ${tmpSource}`);
 			return false;
 		}
 
@@ -255,7 +261,7 @@ class UltravisorBeaconProviderRegistry
 		}
 		else
 		{
-			console.error(`[ProviderRegistry] Invalid provider export from "${tmpSource}": ` +
+			this.log.error(`[ProviderRegistry] Invalid provider export from "${tmpSource}": ` +
 				`must be a class, factory function, or object with execute().`);
 			return false;
 		}

package/source/Ultravisor-Beacon-Service.cjs

@@ -51,7 +51,9 @@ class UltravisorBeaconService extends libFableServiceBase
 			HeartbeatIntervalMs: 30000,
 			StagingPath: '',
 			Tags: {},
-			Contexts: {}
+			Contexts: {},
+			HostID: '',
+			SharedMounts: []
 		}, this.options || {});
 
 		// Internal components
@@ -254,10 +256,23 @@ class UltravisorBeaconService extends libFableServiceBase
 			Contexts: this.options.Contexts || {},
 			BindAddresses: this.options.BindAddresses || [],
 			Operations: this._Operations.length > 0 ? this._Operations : undefined,
+			Log: this.log,
 			// Pass empty Providers array — we'll register adapters directly
 			Providers: []
 		});
 
+		// Shared-fs identity (forwarded to the thin client which sends it to the
+		// coordinator at registration time so the reachability matrix can detect
+		// beacons that share a filesystem on the same host).
+		if (this.options.HostID)
+		{
+			tmpClientConfig.HostID = this.options.HostID;
+		}
+		if (Array.isArray(this.options.SharedMounts) && this.options.SharedMounts.length > 0)
+		{
+			tmpClientConfig.SharedMounts = this.options.SharedMounts;
+		}
+
 		// Create thin client
 		this._ThinClient = new libBeaconClient(tmpClientConfig);
 

package/test/Ultravisor-Beacon-Service_tests.js

@@ -10,12 +10,17 @@
  */
 
 const libAssert = require('assert');
+const libFS = require('fs');
+const libPath = require('path');
+const libCrypto = require('crypto');
+const libOS = require('os');
 
 const libCapabilityProvider = require('../source/Ultravisor-Beacon-CapabilityProvider.cjs');
 const libCapabilityAdapter = require('../source/Ultravisor-Beacon-CapabilityAdapter.cjs');
 const libCapabilityManager = require('../source/Ultravisor-Beacon-CapabilityManager.cjs');
 const libConnectivityHTTP = require('../source/Ultravisor-Beacon-ConnectivityHTTP.cjs');
 const libProviderRegistry = require('../source/Ultravisor-Beacon-ProviderRegistry.cjs');
+const libBeaconClient = require('../source/Ultravisor-Beacon-Client.cjs');
 
 // We can require the service without Fable for standalone testing
 const libBeaconService = require('../source/Ultravisor-Beacon-Service.cjs');
@@ -604,5 +609,136 @@ suite
 				);
 			}
 		);
+
+		// ============================================================
+		// Shared-FS Reachability — SharedMounts normalization
+		// ============================================================
+		suite
+		(
+			'SharedMounts Normalization',
+			function ()
+			{
+				test
+				(
+					'Should return empty array for missing/empty input',
+					function ()
+					{
+						let tmpClient = new libBeaconClient({ Name: 'mt-test', Capabilities: [] });
+						libAssert.deepStrictEqual(tmpClient._normalizeSharedMounts(undefined), []);
+						libAssert.deepStrictEqual(tmpClient._normalizeSharedMounts(null), []);
+						libAssert.deepStrictEqual(tmpClient._normalizeSharedMounts([]), []);
+						libAssert.deepStrictEqual(tmpClient._normalizeSharedMounts('not-an-array'), []);
+					}
+				);
+
+				test
+				(
+					'Should auto-derive MountID from stat.dev + path',
+					function ()
+					{
+						let tmpClient = new libBeaconClient({ Name: 'mt-test', Capabilities: [] });
+						let tmpRoot = libOS.tmpdir();
+						let tmpResolved = libPath.resolve(tmpRoot);
+						let tmpExpected = libCrypto.createHash('sha256')
+							.update(libFS.statSync(tmpResolved).dev + ':' + tmpResolved)
+							.digest('hex').substring(0, 16);
+
+						let tmpResult = tmpClient._normalizeSharedMounts([{ Root: tmpRoot }]);
+						libAssert.strictEqual(tmpResult.length, 1);
+						libAssert.strictEqual(tmpResult[0].MountID, tmpExpected);
+						libAssert.strictEqual(tmpResult[0].Root, tmpResolved);
+					}
+				);
+
+				test
+				(
+					'Should preserve explicit MountID without stat',
+					function ()
+					{
+						let tmpClient = new libBeaconClient({ Name: 'mt-test', Capabilities: [] });
+						let tmpResult = tmpClient._normalizeSharedMounts(
+							[{ MountID: 'manual-id-1234', Root: libOS.tmpdir() }]);
+						libAssert.strictEqual(tmpResult.length, 1);
+						libAssert.strictEqual(tmpResult[0].MountID, 'manual-id-1234');
+					}
+				);
+
+				test
+				(
+					'Should skip entries without a Root',
+					function ()
+					{
+						let tmpClient = new libBeaconClient({ Name: 'mt-test', Capabilities: [] });
+						let tmpResult = tmpClient._normalizeSharedMounts(
+							[{ MountID: 'no-root' }, { Root: libOS.tmpdir() }, null, undefined]);
+						libAssert.strictEqual(tmpResult.length, 1);
+						libAssert.strictEqual(tmpResult[0].Root, libPath.resolve(libOS.tmpdir()));
+					}
+				);
+
+				test
+				(
+					'Should skip entries whose Root does not exist on this beacon',
+					function ()
+					{
+						let tmpClient = new libBeaconClient({ Name: 'mt-test', Capabilities: [] });
+						let tmpResult = tmpClient._normalizeSharedMounts(
+							[{ Root: '/nonexistent-path-12345-xyz' }]);
+						libAssert.deepStrictEqual(tmpResult, []);
+					}
+				);
+
+				test
+				(
+					'Two beacons that point at the same Root should derive identical MountIDs',
+					function ()
+					{
+						let tmpClientA = new libBeaconClient({ Name: 'mt-a', Capabilities: [] });
+						let tmpClientB = new libBeaconClient({ Name: 'mt-b', Capabilities: [] });
+						let tmpA = tmpClientA._normalizeSharedMounts([{ Root: libOS.tmpdir() }]);
+						let tmpB = tmpClientB._normalizeSharedMounts([{ Root: libOS.tmpdir() }]);
+						libAssert.strictEqual(tmpA[0].MountID, tmpB[0].MountID);
+					}
+				);
+			}
+		);
+
+		// ============================================================
+		// BeaconService — HostID and SharedMounts forwarding
+		// ============================================================
+		suite
+		(
+			'Service forwards HostID and SharedMounts',
+			function ()
+			{
+				test
+				(
+					'Service options should accept HostID and SharedMounts with sensible defaults',
+					function ()
+					{
+						let tmpService = new libBeaconService({ Name: 'fwd-test' });
+						// Defaults from Object.assign should land
+						libAssert.strictEqual(tmpService.options.HostID, '');
+						libAssert.deepStrictEqual(tmpService.options.SharedMounts, []);
+					}
+				);
+
+				test
+				(
+					'Service options should preserve caller-supplied HostID and SharedMounts',
+					function ()
+					{
+						let tmpService = new libBeaconService({
+							Name: 'fwd-test',
+							HostID: 'custom-host-id',
+							SharedMounts: [{ MountID: 'abc123', Root: '/data' }]
+						});
+						libAssert.strictEqual(tmpService.options.HostID, 'custom-host-id');
+						libAssert.deepStrictEqual(tmpService.options.SharedMounts,
+							[{ MountID: 'abc123', Root: '/data' }]);
+					}
+				);
+			}
+		);
 	}
 );