ultravisor 1.0.20 → 1.0.21

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ultravisor",
-    "version": "1.0.20",
+    "version": "1.0.21",
     "description": "Cyclic process execution with ai integration.",
     "main": "source/Ultravisor.cjs",
     "bin": {
@@ -31,10 +31,10 @@
         "orator": "^6.0.4",
         "orator-authentication": "^1.0.0",
         "orator-serviceserver-restify": "^2.0.10",
-        "pict": "^1.0.361",
+        "pict": "^1.0.362",
         "pict-service-commandlineutility": "^1.0.19",
         "pict-serviceproviderbase": "^1.0.4",
-        "ultravisor-beacon": "^0.0.10",
+        "ultravisor-beacon": "^0.0.11",
         "ws": "^8.20.0"
     },
     "devDependencies": {

package/source/services/Ultravisor-Beacon-Coordinator.cjs

@@ -1521,7 +1521,7 @@ class UltravisorBeaconCoordinator extends libPictService
 			let tmpContext = tmpManifest.getRun(tmpWorkItem.RunHash);
 			if (tmpContext && tmpContext.WaitingTasks[tmpWorkItem.NodeHash])
 			{
-				tmpContext.WaitingTasks[tmpWorkItem.NodeHash].ResumeEventName = 'Error';
+				tmpContext.WaitingTasks[tmpWorkItem.NodeHash].ResumeEventName = 'error';
 			}
 		}
 

package/source/services/Ultravisor-ExecutionEngine.cjs

@@ -955,11 +955,16 @@ class UltravisorExecutionEngine extends libPictService
 	_resolveStateConnections(pNodeHash, pNode, pContext)
 	{
 		// Start with a copy of the node's static settings
+		// Nodes may store config in Settings or Data (flow editor uses Data)
 		let tmpSettings = {};
 
+		if (pNode.Data && typeof(pNode.Data) === 'object')
+		{
+			tmpSettings = JSON.parse(JSON.stringify(pNode.Data));
+		}
 		if (pNode.Settings && typeof(pNode.Settings) === 'object')
 		{
-			tmpSettings = JSON.parse(JSON.stringify(pNode.Settings));
+			Object.assign(tmpSettings, JSON.parse(JSON.stringify(pNode.Settings)));
 		}
 
 		// Find all incoming State connections targeting this node
@@ -1081,7 +1086,8 @@ class UltravisorExecutionEngine extends libPictService
 			let tmpType = tmpConn.ConnectionType
 				|| this._inferConnectionType(tmpConn, pNodeMap, pPortLabelMap);
 
-			if (tmpType === 'Event')
+			let tmpTypeLower = (tmpType || '').toLowerCase();
+			if (tmpTypeLower === 'event')
 			{
 				if (!tmpMap.eventSources[tmpConn.SourceNodeHash])
 				{
@@ -1089,7 +1095,7 @@ class UltravisorExecutionEngine extends libPictService
 				}
 				tmpMap.eventSources[tmpConn.SourceNodeHash].push(tmpConn);
 			}
-			else if (tmpType === 'State')
+			else if (tmpTypeLower === 'state')
 			{
 				if (!tmpMap.stateTargets[tmpConn.TargetNodeHash])
 				{

package/source/services/tasks/data-transform/Ultravisor-TaskConfigs-DataTransform.cjs

@@ -745,5 +745,77 @@ module.exports =
 				Log: [`Histogram: analyzed ${tmpData.length} records, ${Object.keys(tmpFrequency).length} unique values`]
 			});
 		}
+	},
+
+	// ── random-number ──────────────────────────────────────────────────
+	{
+		Definition: require('./definitions/random-number.json'),
+		Execute: function (pTask, pResolvedSettings, pExecutionContext, fCallback)
+		{
+			let tmpMin = Number(pResolvedSettings.Min);
+			let tmpMax = Number(pResolvedSettings.Max);
+			let tmpInteger = pResolvedSettings.Integer !== false && pResolvedSettings.Integer !== 'false';
+
+			if (isNaN(tmpMin)) tmpMin = 0;
+			if (isNaN(tmpMax)) tmpMax = 2147483647;
+			if (tmpMin >= tmpMax)
+			{
+				return fCallback(null, {
+					EventToFire: 'Error',
+					Outputs: { Value: 0 },
+					Log: [`RandomNumber: Min (${tmpMin}) must be less than Max (${tmpMax})`]
+				});
+			}
+
+			let tmpValue = Math.random() * (tmpMax - tmpMin) + tmpMin;
+			if (tmpInteger)
+			{
+				tmpValue = Math.floor(tmpValue);
+			}
+
+			return fCallback(null, {
+				EventToFire: 'Complete',
+				Outputs: { Value: tmpValue },
+				Log: [`RandomNumber: generated ${tmpValue} in range [${tmpMin}, ${tmpMax})${tmpInteger ? ' (integer)' : ''}`]
+			});
+		}
+	},
+
+	// ── random-string ──────────────────────────────────────────────────
+	{
+		Definition: require('./definitions/random-string.json'),
+		Execute: function (pTask, pResolvedSettings, pExecutionContext, fCallback)
+		{
+			let tmpLength = parseInt(pResolvedSettings.Length, 10) || 16;
+			let tmpFormat = (pResolvedSettings.Format || 'hex').toLowerCase();
+			let tmpValue = '';
+
+			if (tmpFormat === 'uuid')
+			{
+				// RFC 4122 v4 UUID
+				tmpValue = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g,
+					(c) =>
+					{
+						let r = Math.random() * 16 | 0;
+						return (c === 'x' ? r : (r & 0x3 | 0x8)).toString(16);
+					});
+			}
+			else
+			{
+				let tmpChars = tmpFormat === 'alphanumeric'
+					? 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'
+					: '0123456789abcdef';
+				for (let i = 0; i < tmpLength; i++)
+				{
+					tmpValue += tmpChars.charAt(Math.floor(Math.random() * tmpChars.length));
+				}
+			}
+
+			return fCallback(null, {
+				EventToFire: 'Complete',
+				Outputs: { Value: tmpValue },
+				Log: [`RandomString: generated ${tmpFormat} string (${tmpValue.length} chars)`]
+			});
+		}
 	}
 ];

package/source/services/tasks/data-transform/definitions/random-number.json

@@ -0,0 +1,24 @@
+{
+	"Hash": "random-number",
+	"Type": "random-number",
+	"Name": "Random Number",
+	"Description": "Generates a random number within a specified range. Use Integer=true for whole numbers (e.g., seeds), false for decimals.",
+	"Category": "data",
+	"Capability": "Data Transform",
+	"Action": "GenerateRandomNumber",
+	"Tier": "Engine",
+	"EventInputs": [{ "Name": "Generate" }],
+	"EventOutputs": [
+		{ "Name": "Complete" },
+		{ "Name": "Error", "IsError": true }
+	],
+	"SettingsInputs": [
+		{ "Name": "Min", "DataType": "Number", "Required": false, "Description": "Minimum value (inclusive). Default: 0" },
+		{ "Name": "Max", "DataType": "Number", "Required": false, "Description": "Maximum value (exclusive for float, inclusive for integer). Default: 2147483647" },
+		{ "Name": "Integer", "DataType": "Boolean", "Required": false, "Description": "If true, generate a whole number. Default: true" }
+	],
+	"StateOutputs": [
+		{ "Name": "Value", "DataType": "Number", "Description": "The generated random number" }
+	],
+	"DefaultSettings": { "Min": 0, "Max": 2147483647, "Integer": true }
+}

package/source/services/tasks/data-transform/definitions/random-string.json

@@ -0,0 +1,23 @@
+{
+	"Hash": "random-string",
+	"Type": "random-string",
+	"Name": "Random String",
+	"Description": "Generates a random string. Useful for unique filenames, run IDs, and identifiers.",
+	"Category": "data",
+	"Capability": "Data Transform",
+	"Action": "GenerateRandomString",
+	"Tier": "Engine",
+	"EventInputs": [{ "Name": "Generate" }],
+	"EventOutputs": [
+		{ "Name": "Complete" },
+		{ "Name": "Error", "IsError": true }
+	],
+	"SettingsInputs": [
+		{ "Name": "Length", "DataType": "Number", "Required": false, "Description": "Length of the generated string. Default: 16" },
+		{ "Name": "Format", "DataType": "String", "Required": false, "Description": "Format: hex, alphanumeric, uuid. Default: hex" }
+	],
+	"StateOutputs": [
+		{ "Name": "Value", "DataType": "String", "Description": "The generated random string" }
+	],
+	"DefaultSettings": { "Length": 16, "Format": "hex" }
+}

package/source/services/tasks/extension/Ultravisor-TaskConfigs-Extension.cjs

@@ -46,12 +46,24 @@ module.exports =
 				});
 			}
 
-			// Build work item settings from resolved settings
-			let tmpSettings = {
-				Command: pResolvedSettings.Command || '',
-				Parameters: pResolvedSettings.Parameters || '',
-				InputData: pResolvedSettings.InputData || ''
-			};
+			// Build work item settings from ALL resolved settings
+			// (includes node Data fields + state connection values)
+			let tmpSettings = {};
+			let tmpResolvedKeys = Object.keys(pResolvedSettings);
+			for (let rk = 0; rk < tmpResolvedKeys.length; rk++)
+			{
+				let tmpKey = tmpResolvedKeys[rk];
+				// Skip internal/meta fields that aren't work item settings
+				if (tmpKey === 'RemoteCapability' || tmpKey === 'RemoteAction'
+					|| tmpKey === 'AffinityKey' || tmpKey === 'TimeoutMs'
+					|| tmpKey === 'PromptMessage' || tmpKey === 'OutputAddress'
+					|| tmpKey === 'InputSchema') continue;
+				tmpSettings[tmpKey] = pResolvedSettings[tmpKey];
+			}
+			// Ensure legacy fields exist for backward compat
+			if (!tmpSettings.Command) tmpSettings.Command = '';
+			if (!tmpSettings.Parameters) tmpSettings.Parameters = '';
+			if (!tmpSettings.InputData) tmpSettings.InputData = '';
 
 			// Resolve universal addresses in InputData (JSON string).
 			// Addresses like >retold-remote/File/path become concrete
@@ -122,7 +134,7 @@ module.exports =
 			// Pause execution — the BeaconCoordinator will call resumeOperation when the Beacon reports back
 			return fCallback(null, {
 				WaitingForInput: true,
-				ResumeEventName: 'Complete',
+				ResumeEventName: 'complete',
 				PromptMessage: `Waiting for Beacon worker (${tmpWorkItemInfo.Capability}/${tmpWorkItemInfo.Action})`,
 				OutputAddress: '',
 				Outputs: {},

package/source/services/tasks/user-interaction/Ultravisor-TaskConfigs-UserInteraction.cjs

@@ -106,14 +106,42 @@ module.exports =
 				if (tmpExistingValue !== undefined && tmpExistingValue !== null && tmpExistingValue !== '')
 				{
 					return fCallback(null, {
-						EventToFire: 'ValueInputComplete',
+						EventToFire: 'complete',
 						Outputs: { InputValue: tmpExistingValue },
 						Log: [`Auto-resolved from pre-seeded state: "${tmpOutputAddress}" = "${String(tmpExistingValue).substring(0, 100)}"`]
 					});
 				}
 			}
 
-			// No pre-seeded value — pause and wait for interactive input
+			// If the operation was triggered programmatically (has pre-seeded params),
+			// use the DefaultValue so the whole chain runs without pausing
+			let tmpIsProgrammatic = pExecutionContext.OperationState
+				&& Object.keys(pExecutionContext.OperationState).length > 0;
+			let tmpDefaultValue = pResolvedSettings.DefaultValue
+				|| (pResolvedSettings.InputSchema && pResolvedSettings.InputSchema.Default !== undefined
+					? String(pResolvedSettings.InputSchema.Default) : undefined);
+			if (tmpIsProgrammatic && tmpDefaultValue !== undefined && tmpDefaultValue !== null && tmpDefaultValue !== '')
+			{
+				return fCallback(null, {
+					EventToFire: 'complete',
+					Outputs: { InputValue: tmpDefaultValue },
+					Log: [`Auto-resolved from default: "${tmpOutputAddress}" = "${String(tmpDefaultValue).substring(0, 100)}"`]
+				});
+			}
+
+			// For optional fields with no default in programmatic mode, pass empty string
+			let tmpIsOptional = pResolvedSettings.InputSchema
+				&& pResolvedSettings.InputSchema.Required === false;
+			if (tmpIsProgrammatic && tmpIsOptional)
+			{
+				return fCallback(null, {
+					EventToFire: 'complete',
+					Outputs: { InputValue: '' },
+					Log: [`Auto-resolved optional field: "${tmpOutputAddress}" = "" (no value provided)`]
+				});
+			}
+
+			// No pre-seeded value and no default — pause and wait for interactive input
 			let tmpOptions = pResolvedSettings.Options || '';
 			if (Array.isArray(tmpOptions))
 			{

package/source/services/tasks/user-interaction/Ultravisor-TaskType-ValueInput.cjs

@@ -29,15 +29,69 @@ class UltravisorTaskTypeValueInput extends libTaskTypeBase
 		let tmpPromptMessage = pResolvedSettings.PromptMessage || 'Please provide a value:';
 		let tmpOutputAddress = pResolvedSettings.OutputAddress || '';
 
-		// Signal that this task is waiting for input
+		// Auto-resolve: if the output address already has a value in state
+		// (e.g., pre-seeded via /Operation/:Hash/Trigger with Parameters),
+		// skip the pause and fire immediately. This lets operations work both
+		// interactively (flow editor — pauses for input) and programmatically
+		// (API trigger / retold-labs operation runner — runs straight through).
+		if (tmpOutputAddress && pExecutionContext.StateManager)
+		{
+			let tmpExistingValue = pExecutionContext.StateManager.resolveAddress(
+				tmpOutputAddress, pExecutionContext, pExecutionContext.NodeHash);
+			if (tmpExistingValue !== undefined && tmpExistingValue !== null && tmpExistingValue !== '')
+			{
+				return fCallback(null, {
+					EventToFire: 'complete',
+					Outputs: { InputValue: tmpExistingValue },
+					Log: [`Auto-resolved from pre-seeded state: "${tmpOutputAddress}" = "${String(tmpExistingValue).substring(0, 100)}"`]
+				});
+			}
+		}
+
+		// If the operation was triggered programmatically (OperationState has pre-seeded values),
+		// auto-resolve using the DefaultValue so the whole chain runs without pausing.
+		// In interactive mode (empty OperationState), pause for user input.
+		let tmpIsProgrammatic = pExecutionContext.OperationState
+			&& Object.keys(pExecutionContext.OperationState).length > 0;
+		let tmpDefaultValue = pResolvedSettings.DefaultValue
+			|| (pResolvedSettings.InputSchema && pResolvedSettings.InputSchema.Default !== undefined
+				? String(pResolvedSettings.InputSchema.Default) : undefined);
+		if (tmpIsProgrammatic && tmpDefaultValue !== undefined && tmpDefaultValue !== null && tmpDefaultValue !== '')
+		{
+			return fCallback(null, {
+				EventToFire: 'complete',
+				Outputs: { InputValue: tmpDefaultValue },
+				Log: [`Auto-resolved from default: "${tmpOutputAddress}" = "${String(tmpDefaultValue).substring(0, 100)}"`]
+			});
+		}
+
+		// For optional fields with no default in programmatic mode, pass empty string
+		let tmpIsOptional = pResolvedSettings.InputSchema
+			&& pResolvedSettings.InputSchema.Required === false;
+		if (tmpIsProgrammatic && tmpIsOptional)
+		{
+			return fCallback(null, {
+				EventToFire: 'complete',
+				Outputs: { InputValue: '' },
+				Log: [`Auto-resolved optional field: "${tmpOutputAddress}" = "" (no value provided)`]
+			});
+		}
+
+		// No pre-seeded value and no default — pause and wait for interactive input
 		// The ExecutionEngine will set the run to WaitingForInput status
+		let tmpOptions = pResolvedSettings.Options || '';
+		if (Array.isArray(tmpOptions))
+		{
+			tmpOptions = JSON.stringify(tmpOptions);
+		}
+
 		return fCallback(null, {
 			WaitingForInput: true,
 			PromptMessage: tmpPromptMessage,
 			OutputAddress: tmpOutputAddress,
 			InputType: pResolvedSettings.InputType || 'text',
 			DefaultValue: pResolvedSettings.DefaultValue || '',
-			Options: pResolvedSettings.Options || '',
+			Options: tmpOptions,
 			Outputs: {},
 			Log: [`Waiting for input: "${tmpPromptMessage}" (-> ${tmpOutputAddress})`]
 		});

package/source/web_server/Ultravisor-API-Server.cjs

@@ -2055,6 +2055,16 @@ class UltravisorAPIServer extends libPictService
 			return;
 		}
 
+		// Diagnostic: log what we RECEIVED from the client before forwarding
+		// to registerBeacon. If the client sent HostID but we're storing null,
+		// this log line pins down exactly where the drop happens (client vs
+		// server). Gated on LogNoisiness>=2 to stay quiet in production.
+		let tmpNoisy = (this.fable && this.fable.LogNoisiness) || 0;
+		if (tmpNoisy >= 2)
+		{
+			this.log.info(`[WSRegister] received from client: Name=${pData.Name} HostID=${pData.HostID || '(none)'} SharedMounts=${JSON.stringify(pData.SharedMounts || [])} Ops=${(pData.Operations || []).length}`);
+		}
+
 		// IMPORTANT: this enumeration must include every field the coordinator
 		// cares about, including HostID and SharedMounts (used by the shared-fs
 		// reachability auto-detect). Forgetting to forward a field here means
@@ -2073,6 +2083,12 @@ class UltravisorAPIServer extends libPictService
 			SharedMounts: pData.SharedMounts
 		});
 
+		// Diagnostic: confirm what was actually STORED on the beacon record.
+		if (tmpNoisy >= 2)
+		{
+			this.log.info(`[WSRegister] stored beacon ${tmpBeacon.BeaconID}: HostID=${tmpBeacon.HostID || '(null)'} SharedMounts=${JSON.stringify(tmpBeacon.SharedMounts || [])}`);
+		}
+
 		pWebSocket._BeaconID = tmpBeacon.BeaconID;
 		this._BeaconWebSockets[tmpBeacon.BeaconID] = pWebSocket;
 

package/test/Ultravisor-Beacon-Reachability_tests.js

@@ -0,0 +1,520 @@
+/**
+ * Unit tests for the UltravisorBeaconReachability service, specifically the
+ * shared-fs reachability strategy (findSharedFsPeer + resolveStrategy).
+ *
+ * These tests exist to catch regressions in the logic that decides whether
+ * two beacons can skip the HTTP file-transfer layer because they share a
+ * filesystem on the same host. The shared-fs optimization is nearly invisible
+ * when it works (you just see faster thumbnails) and almost invisible when it
+ * silently stops working (you see slower thumbnails and a lot more bandwidth).
+ * The only way to catch regressions early is to assert the branch behavior
+ * of `findSharedFsPeer` and `resolveStrategy` directly, with mocked coordinator
+ * state standing in for a real running Ultravisor.
+ *
+ * Test layout:
+ *
+ *   findSharedFsPeer
+ *     - positive match: two beacons, same host, overlapping mount → MATCH
+ *     - negative: source beacon missing HostID (legacy) → null
+ *     - negative: source beacon has empty SharedMounts → null
+ *     - negative: source beacon missing entirely → null
+ *     - negative: no coordinator service registered → null
+ *     - negative: only the source beacon exists (no peers) → null
+ *     - negative: peer on different host → null
+ *     - negative: peer on same host but no overlapping MountID → null
+ *     - negative: peer is Offline → null
+ *     - positive: multiple peers, one matches → MATCH (first match wins)
+ *
+ *   resolveStrategy
+ *     - local (same beacon) → Strategy: local
+ *     - shared-fs (same host, overlapping mount) → Strategy: shared-fs + root
+ *     - direct (different host, reachable matrix) → Strategy: direct
+ *     - proxy fallback (matrix says unreachable/untested) → Strategy: proxy
+ *
+ *   _findSharedMount
+ *     - helper-level tests for the pure mount-overlap logic
+ */
+
+const libPict = require('pict');
+const libUltravisorBeaconReachability = require('../source/services/Ultravisor-Beacon-Reachability.cjs');
+
+var Chai = require('chai');
+var Expect = Chai.expect;
+
+/**
+ * Build a Pict instance with a MOCK BeaconCoordinator and the real
+ * Reachability service. The coordinator mock exposes the same two methods
+ * (getBeacon, listBeacons) that Reachability consumes, so we can construct
+ * arbitrary beacon topologies without spinning up the real coordinator.
+ *
+ * @param {Object<string, object>} pBeacons - Keyed by BeaconID
+ * @returns {{ fable, reachability, coordinator }}
+ */
+function _buildTestHarness(pBeacons)
+{
+	let tmpFable = new libPict(
+		{
+			Product: 'Ultravisor-Test-Reachability',
+			LogLevel: 5
+		});
+
+	// Mock coordinator — just enough surface area for Reachability to work.
+	let tmpMockCoordinator =
+		{
+			serviceType: 'UltravisorBeaconCoordinator',
+			Hash: 'MockCoordinator',
+			_Beacons: pBeacons || {},
+			getBeacon: function (pBeaconID)
+			{
+				return this._Beacons[pBeaconID] || null;
+			},
+			listBeacons: function ()
+			{
+				return Object.values(this._Beacons);
+			},
+			setBeacons: function (pNewBeacons)
+			{
+				this._Beacons = pNewBeacons || {};
+			}
+		};
+
+	// Register the mock under the same name Reachability expects.
+	if (!tmpFable.servicesMap['UltravisorBeaconCoordinator'])
+	{
+		tmpFable.servicesMap['UltravisorBeaconCoordinator'] = {};
+	}
+	tmpFable.servicesMap['UltravisorBeaconCoordinator'][tmpMockCoordinator.Hash] = tmpMockCoordinator;
+
+	// Instantiate the real Reachability service.
+	tmpFable.addAndInstantiateServiceTypeIfNotExists('UltravisorBeaconReachability', libUltravisorBeaconReachability);
+	let tmpReachability = Object.values(tmpFable.servicesMap['UltravisorBeaconReachability'])[0];
+
+	return {
+		fable: tmpFable,
+		reachability: tmpReachability,
+		coordinator: tmpMockCoordinator
+	};
+}
+
+/**
+ * Helper: build a fake beacon record. Anything not specified defaults to the
+ * "typical online beacon on host-alpha with one shared mount" shape.
+ */
+function _beacon(pOverrides)
+{
+	let tmpBase =
+		{
+			BeaconID: 'bcn-default',
+			Name: 'default',
+			Status: 'Online',
+			HostID: 'host-alpha',
+			SharedMounts: [{ MountID: 'mnt-1', Root: '/data' }],
+			Contexts: { File: { BasePath: '/data', BaseURL: '/content/' } },
+			BindAddresses: [{ IP: '10.0.0.2', Port: 7777, Protocol: 'http' }]
+		};
+	return Object.assign(tmpBase, pOverrides || {});
+}
+
+suite
+(
+	'Ultravisor Beacon Reachability',
+	function ()
+	{
+		// ================================================================
+		// findSharedFsPeer
+		// ================================================================
+		suite
+		(
+			'findSharedFsPeer',
+			function ()
+			{
+				test
+				(
+					'returns null when the coordinator service is not registered',
+					function ()
+					{
+						let tmpFable = new libPict({ Product: 'Ultravisor-Test-Reachability', LogLevel: 5 });
+						// Note: NO coordinator registered — simulate a broken test harness
+						tmpFable.addAndInstantiateServiceTypeIfNotExists('UltravisorBeaconReachability', libUltravisorBeaconReachability);
+						let tmpReachability = Object.values(tmpFable.servicesMap['UltravisorBeaconReachability'])[0];
+
+						Expect(tmpReachability.findSharedFsPeer('bcn-whatever')).to.equal(null);
+					}
+				);
+
+				test
+				(
+					'returns null when the source beacon is not in the coordinator registry',
+					function ()
+					{
+						let tmpHarness = _buildTestHarness({});
+						Expect(tmpHarness.reachability.findSharedFsPeer('bcn-ghost')).to.equal(null);
+					}
+				);
+
+				test
+				(
+					'returns null when the source beacon has no HostID (legacy beacon)',
+					function ()
+					{
+						let tmpHarness = _buildTestHarness(
+							{
+								'bcn-legacy': _beacon({ BeaconID: 'bcn-legacy', HostID: null }),
+								'bcn-peer': _beacon({ BeaconID: 'bcn-peer', HostID: 'host-alpha' })
+							});
+						Expect(tmpHarness.reachability.findSharedFsPeer('bcn-legacy')).to.equal(null);
+					}
+				);
+
+				test
+				(
+					'returns null when the source beacon has an empty SharedMounts array',
+					function ()
+					{
+						let tmpHarness = _buildTestHarness(
+							{
+								'bcn-empty': _beacon({ BeaconID: 'bcn-empty', SharedMounts: [] }),
+								'bcn-peer': _beacon({ BeaconID: 'bcn-peer' })
+							});
+						Expect(tmpHarness.reachability.findSharedFsPeer('bcn-empty')).to.equal(null);
+					}
+				);
+
+				test
+				(
+					'returns null when only the source beacon is registered (no peers at all)',
+					function ()
+					{
+						let tmpHarness = _buildTestHarness(
+							{
+								'bcn-lonely': _beacon({ BeaconID: 'bcn-lonely' })
+							});
+						Expect(tmpHarness.reachability.findSharedFsPeer('bcn-lonely')).to.equal(null);
+					}
+				);
+
+				test
+				(
+					'returns null when the peer is on a different host',
+					function ()
+					{
+						let tmpHarness = _buildTestHarness(
+							{
+								'bcn-source': _beacon({ BeaconID: 'bcn-source', HostID: 'host-alpha' }),
+								'bcn-remote': _beacon({ BeaconID: 'bcn-remote', HostID: 'host-beta' })
+							});
+						Expect(tmpHarness.reachability.findSharedFsPeer('bcn-source')).to.equal(null);
+					}
+				);
+
+				test
+				(
+					'returns null when the peer shares a host but has no overlapping MountID',
+					function ()
+					{
+						let tmpHarness = _buildTestHarness(
+							{
+								'bcn-source': _beacon(
+									{
+										BeaconID: 'bcn-source',
+										SharedMounts: [{ MountID: 'mnt-alpha', Root: '/data-alpha' }]
+									}),
+								'bcn-peer': _beacon(
+									{
+										BeaconID: 'bcn-peer',
+										SharedMounts: [{ MountID: 'mnt-beta', Root: '/data-beta' }]
+									})
+							});
+						Expect(tmpHarness.reachability.findSharedFsPeer('bcn-source')).to.equal(null);
+					}
+				);
+
+				test
+				(
+					'returns null when the only matching peer is Offline',
+					function ()
+					{
+						let tmpHarness = _buildTestHarness(
+							{
+								'bcn-source': _beacon({ BeaconID: 'bcn-source' }),
+								'bcn-dead': _beacon({ BeaconID: 'bcn-dead', Status: 'Offline' })
+							});
+						Expect(tmpHarness.reachability.findSharedFsPeer('bcn-source')).to.equal(null);
+					}
+				);
+
+				test
+				(
+					'returns a MATCH when a peer shares host and MountID (happy path)',
+					function ()
+					{
+						let tmpHarness = _buildTestHarness(
+							{
+								'bcn-retold-remote': _beacon({ BeaconID: 'bcn-retold-remote' }),
+								'bcn-orator-conversion': _beacon({ BeaconID: 'bcn-orator-conversion' })
+							});
+						let tmpResult = tmpHarness.reachability.findSharedFsPeer('bcn-retold-remote');
+						Expect(tmpResult).to.not.equal(null);
+						Expect(tmpResult.Peer.BeaconID).to.equal('bcn-orator-conversion');
+						Expect(tmpResult.Mount.MountID).to.equal('mnt-1');
+						Expect(tmpResult.Mount.Root).to.equal('/data');
+					}
+				);
+
+				test
+				(
+					'returns the first MATCH when multiple peers share host+mount',
+					function ()
+					{
+						let tmpHarness = _buildTestHarness(
+							{
+								'bcn-source': _beacon({ BeaconID: 'bcn-source' }),
+								'bcn-peer-1': _beacon({ BeaconID: 'bcn-peer-1' }),
+								'bcn-peer-2': _beacon({ BeaconID: 'bcn-peer-2' })
+							});
+						let tmpResult = tmpHarness.reachability.findSharedFsPeer('bcn-source');
+						Expect(tmpResult).to.not.equal(null);
+						// Whichever peer is first in listBeacons iteration order wins — we
+						// don't care which; we just care that SOMETHING matched.
+						Expect(['bcn-peer-1', 'bcn-peer-2']).to.include(tmpResult.Peer.BeaconID);
+					}
+				);
+
+				test
+				(
+					'does not match the source beacon against itself',
+					function ()
+					{
+						let tmpHarness = _buildTestHarness(
+							{
+								'bcn-solo': _beacon({ BeaconID: 'bcn-solo' })
+							});
+						// With only the source beacon in the registry, no match.
+						Expect(tmpHarness.reachability.findSharedFsPeer('bcn-solo')).to.equal(null);
+					}
+				);
+
+				test
+				(
+					'finds a peer when source has multiple mounts and at least one overlaps',
+					function ()
+					{
+						let tmpHarness = _buildTestHarness(
+							{
+								'bcn-source': _beacon(
+									{
+										BeaconID: 'bcn-source',
+										SharedMounts: [
+											{ MountID: 'mnt-content', Root: '/media' },
+											{ MountID: 'mnt-cache', Root: '/cache' },
+											{ MountID: 'mnt-config', Root: '/config' }
+										]
+									}),
+								'bcn-peer': _beacon(
+									{
+										BeaconID: 'bcn-peer',
+										SharedMounts: [
+											{ MountID: 'mnt-cache', Root: '/cache' }
+										]
+									})
+							});
+						let tmpResult = tmpHarness.reachability.findSharedFsPeer('bcn-source');
+						Expect(tmpResult).to.not.equal(null);
+						Expect(tmpResult.Mount.MountID).to.equal('mnt-cache');
+						Expect(tmpResult.Mount.Root).to.equal('/cache');
+					}
+				);
+			}
+		);
+
+		// ================================================================
+		// resolveStrategy
+		// ================================================================
+		suite
+		(
+			'resolveStrategy',
+			function ()
+			{
+				test
+				(
+					'returns Strategy=local when source and requesting beacon are the same',
+					function ()
+					{
+						let tmpHarness = _buildTestHarness(
+							{
+								'bcn-only': _beacon({ BeaconID: 'bcn-only' })
+							});
+						let tmpResult = tmpHarness.reachability.resolveStrategy('bcn-only', 'bcn-only');
+						Expect(tmpResult.Strategy).to.equal('local');
+					}
+				);
+
+				test
+				(
+					'returns Strategy=shared-fs when beacons share host+mount',
+					function ()
+					{
+						let tmpHarness = _buildTestHarness(
+							{
+								'bcn-source': _beacon({ BeaconID: 'bcn-source' }),
+								'bcn-consumer': _beacon({ BeaconID: 'bcn-consumer' })
+							});
+						let tmpResult = tmpHarness.reachability.resolveStrategy('bcn-source', 'bcn-consumer');
+						Expect(tmpResult.Strategy).to.equal('shared-fs');
+						Expect(tmpResult.SharedMountRoot).to.equal('/data');
+					}
+				);
+
+				test
+				(
+					'returns Strategy=proxy when beacons are on different hosts and reachability is untested',
+					function ()
+					{
+						let tmpHarness = _buildTestHarness(
+							{
+								'bcn-source': _beacon({ BeaconID: 'bcn-source', HostID: 'host-alpha' }),
+								'bcn-remote': _beacon({ BeaconID: 'bcn-remote', HostID: 'host-beta' })
+							});
+						// Untested matrix → falls through to proxy
+						let tmpResult = tmpHarness.reachability.resolveStrategy('bcn-source', 'bcn-remote');
+						Expect(tmpResult.Strategy).to.equal('proxy');
+					}
+				);
+
+				test
+				(
+					'returns Strategy=direct when the matrix says the pair is reachable',
+					function ()
+					{
+						let tmpHarness = _buildTestHarness(
+							{
+								'bcn-source': _beacon({ BeaconID: 'bcn-source', HostID: 'host-alpha' }),
+								'bcn-remote': _beacon({ BeaconID: 'bcn-remote', HostID: 'host-beta' })
+							});
+						// Stub the reachability matrix to say these two CAN reach each other
+						tmpHarness.reachability.getReachability = function ()
+						{
+							return { Status: 'reachable' };
+						};
+						let tmpResult = tmpHarness.reachability.resolveStrategy('bcn-source', 'bcn-remote');
+						Expect(tmpResult.Strategy).to.equal('direct');
+						Expect(tmpResult.DirectURL).to.be.a('string');
+					}
+				);
+
+				test
+				(
+					'returns Strategy=proxy when the source beacon does not exist in the registry',
+					function ()
+					{
+						let tmpHarness = _buildTestHarness(
+							{
+								'bcn-requestor': _beacon({ BeaconID: 'bcn-requestor' })
+							});
+						let tmpResult = tmpHarness.reachability.resolveStrategy('bcn-vanished', 'bcn-requestor');
+						Expect(tmpResult.Strategy).to.equal('proxy');
+					}
+				);
+
+				test
+				(
+					'prefers shared-fs over direct when both are possible',
+					function ()
+					{
+						let tmpHarness = _buildTestHarness(
+							{
+								'bcn-source': _beacon({ BeaconID: 'bcn-source' }),
+								'bcn-consumer': _beacon({ BeaconID: 'bcn-consumer' })
+							});
+						// Even if the matrix says they're reachable via HTTP, shared-fs
+						// should still win because it's cheaper.
+						tmpHarness.reachability.getReachability = function ()
+						{
+							return { Status: 'reachable' };
+						};
+						let tmpResult = tmpHarness.reachability.resolveStrategy('bcn-source', 'bcn-consumer');
+						Expect(tmpResult.Strategy).to.equal('shared-fs');
+					}
+				);
+
+				test
+				(
+					'falls back to direct/proxy when one of the beacons is a legacy (no HostID) beacon',
+					function ()
+					{
+						let tmpHarness = _buildTestHarness(
+							{
+								'bcn-legacy': _beacon({ BeaconID: 'bcn-legacy', HostID: null }),
+								'bcn-modern': _beacon({ BeaconID: 'bcn-modern' })
+							});
+						// A legacy beacon can't participate in shared-fs — should fall
+						// through to the matrix-based direct/proxy decision.
+						let tmpResult = tmpHarness.reachability.resolveStrategy('bcn-legacy', 'bcn-modern');
+						Expect(tmpResult.Strategy).to.not.equal('shared-fs');
+						Expect(['direct', 'proxy']).to.include(tmpResult.Strategy);
+					}
+				);
+			}
+		);
+
+		// ================================================================
+		// _findSharedMount (helper)
+		// ================================================================
+		suite
+		(
+			'_findSharedMount',
+			function ()
+			{
+				test
+				(
+					'returns null for empty or missing arrays',
+					function ()
+					{
+						let tmpHarness = _buildTestHarness({});
+						let tmpR = tmpHarness.reachability;
+						Expect(tmpR._findSharedMount(null, null)).to.equal(null);
+						Expect(tmpR._findSharedMount(undefined, undefined)).to.equal(null);
+						Expect(tmpR._findSharedMount([], [])).to.equal(null);
+						Expect(tmpR._findSharedMount([{ MountID: 'x' }], [])).to.equal(null);
+						Expect(tmpR._findSharedMount([], [{ MountID: 'x' }])).to.equal(null);
+					}
+				);
+
+				test
+				(
+					'returns the first matching mount from the source side',
+					function ()
+					{
+						let tmpHarness = _buildTestHarness({});
+						let tmpMatch = tmpHarness.reachability._findSharedMount(
+							[
+								{ MountID: 'a', Root: '/root-a' },
+								{ MountID: 'b', Root: '/root-b' }
+							],
+							[
+								{ MountID: 'b', Root: '/root-b-as-seen-by-peer' }
+							]);
+						Expect(tmpMatch).to.not.equal(null);
+						Expect(tmpMatch.MountID).to.equal('b');
+						// Source-side root wins — which matters because the dispatcher
+						// uses this Root to build the LocalPath for the requesting side.
+						Expect(tmpMatch.Root).to.equal('/root-b');
+					}
+				);
+
+				test
+				(
+					'skips entries that have no MountID',
+					function ()
+					{
+						let tmpHarness = _buildTestHarness({});
+						Expect(tmpHarness.reachability._findSharedMount(
+							[{ Root: '/a' }, { MountID: 'c', Root: '/c' }],
+							[{ MountID: 'c', Root: '/c' }]
+						).MountID).to.equal('c');
+					}
+				);
+			}
+		);
+	}
+);

package/test/Ultravisor_tests.js

@@ -190,7 +190,7 @@ suite
 						Expect(tmpInstance.definition.Hash).to.equal('read-file');
 
 						let tmpDefs = tmpRegistry.listDefinitions();
-						Expect(tmpDefs.length).to.equal(54);
+						Expect(tmpDefs.length).to.equal(56);
 
 						// Verify all registered definitions have Capability, Action, and Tier
 						for (let i = 0; i < tmpDefs.length; i++)
@@ -1806,7 +1806,7 @@ suite
 						let tmpBuiltInConfigs = require('../source/services/tasks/Ultravisor-BuiltIn-TaskConfigs.cjs');
 						let tmpCount = tmpRegistry.registerTaskTypesFromConfigArray(tmpBuiltInConfigs);
 
-						Expect(tmpCount).to.equal(54);
+						Expect(tmpCount).to.equal(56);
 
 						// Spot-check a few
 						Expect(tmpRegistry.hasTaskType('error-message')).to.equal(true);
@@ -1991,7 +1991,7 @@ suite
 
 						// Configs already registered by createTestFable — verify all present
 						let tmpDefs = tmpRegistry.listDefinitions();
-						Expect(tmpDefs.length).to.equal(54);
+						Expect(tmpDefs.length).to.equal(56);
 					}
 				);
 			}
@@ -3877,7 +3877,7 @@ suite
 
 									// Verify WaitingTasks has the dispatch node
 									Expect(pContext.WaitingTasks['dispatch-1']).to.not.equal(undefined);
-									Expect(pContext.WaitingTasks['dispatch-1'].ResumeEventName).to.equal('Complete');
+									Expect(pContext.WaitingTasks['dispatch-1'].ResumeEventName).to.equal('complete');
 
 									// Verify a work item was enqueued
 									let tmpWorkItems = tmpCoordinator.listWorkItems();