ultravisor 1.3.19 → 1.3.21

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ultravisor",
-	"version": "1.3.19",
+	"version": "1.3.21",
 	"description": "Cyclic process execution with ai integration.",
 	"main": "source/Ultravisor.cjs",
 	"bin": {
@@ -55,18 +55,18 @@
 	"homepage": "https://github.com/stevenvelozo/ultravisor#readme",
 	"dependencies": {
 		"cron": "^4.4.0",
-		"meadow": "^2.0.43",
+		"meadow": "^2.0.44",
 		"meadow-connection-sqlite": "^1.0.20",
-		"meadow-migrationmanager": "^1.0.4",
+		"meadow-migrationmanager": "^1.0.5",
 		"orator": "^6.1.2",
-		"orator-authentication": "^1.0.4",
+		"orator-authentication": "^1.0.6",
 		"orator-serviceserver-restify": "^2.0.11",
-		"pict": "^1.0.372",
-		"pict-service-commandlineutility": "^1.0.19",
+		"pict": "^1.0.381",
+		"pict-service-commandlineutility": "^1.0.20",
 		"pict-serviceproviderbase": "^1.0.4",
-		"ultravisor-beacon": "^1.0.4",
+		"ultravisor-beacon": "^1.0.5",
 		"ultravisor-file-stream": "^1.0.0",
-		"ws": "^8.20.0"
+		"ws": "^8.21.0"
 	},
 	"devDependencies": {
 		"pict-docuserve": "^1.4.19",

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

@@ -640,8 +640,10 @@ class UltravisorBeaconCoordinator extends libPictService
 
 			// Add standard beacon dispatch settings
 			tmpSettingsInputs.push({ Name: 'AffinityKey', DataType: 'String', Required: false, Description: 'Sticky routing key for beacon affinity.' });
+			tmpSettingsInputs.push({ Name: 'RequireAffinityMatch', DataType: 'Boolean', Required: false, Description: 'Strict routing: AffinityKey must match a registered beacon Name; the item waits for that beacon instead of falling back to any capable one.' });
 			tmpSettingsInputs.push({ Name: 'TimeoutMs', DataType: 'Number', Required: false, Description: 'Work item timeout in milliseconds.' });
 			tmpDefaultSettings.AffinityKey = '';
+			tmpDefaultSettings.RequireAffinityMatch = false;
 			tmpDefaultSettings.TimeoutMs = 300000;
 
 			// Derive a display name from the action
@@ -713,6 +715,7 @@ class UltravisorBeaconCoordinator extends libPictService
 			// Build settings object from resolved settings, excluding beacon dispatch meta-fields
 			let tmpSettings = Object.assign({}, pResolvedSettings);
 			delete tmpSettings.AffinityKey;
+			delete tmpSettings.RequireAffinityMatch;
 			delete tmpSettings.TimeoutMs;
 
 			// Coerce types based on schema
@@ -742,6 +745,7 @@ class UltravisorBeaconCoordinator extends libPictService
 				Action: pAction,
 				Settings: tmpSettings,
 				AffinityKey: pResolvedSettings.AffinityKey || '',
+				RequireAffinityMatch: !!pResolvedSettings.RequireAffinityMatch,
 				TimeoutMs: pResolvedSettings.TimeoutMs || 300000
 			}, pExecutionContext, fCallback);
 		};
@@ -1115,6 +1119,7 @@ class UltravisorBeaconCoordinator extends libPictService
 			Action: pWorkItemInfo.Action || 'Execute',
 			Settings: tmpSettings,
 			AffinityKey: pWorkItemInfo.AffinityKey || '',
+			RequireAffinityMatch: !!pWorkItemInfo.RequireAffinityMatch,
 			AssignedBeaconID: null,
 			Status: 'Pending',
 			TimeoutMs: pWorkItemInfo.TimeoutMs || tmpDefaultTimeout,
@@ -1176,6 +1181,14 @@ class UltravisorBeaconCoordinator extends libPictService
 				tmpNamedBeacon.CurrentWorkItems.push(tmpWorkItemHash);
 				this.log.info(`BeaconCoordinator: work item [${tmpWorkItemHash}] routed by name to beacon [${tmpNamedBeacon.BeaconID}] (Name=${tmpNamedBeacon.Name}) via AffinityKey [${tmpWorkItem.AffinityKey}].`);
 			}
+			else if (tmpWorkItem.RequireAffinityMatch)
+			{
+				// Strict routing: the designated beacon is not registered right
+				// now (offline / mid-restart). The item stays Pending and only
+				// that beacon may claim it when it returns — never another
+				// capable beacon. The normal work-item timeout bounds the wait.
+				this.log.warn(`BeaconCoordinator: work item [${tmpWorkItemHash}] requires beacon [${tmpWorkItem.AffinityKey}], which is not registered — holding pending until it returns.`);
+			}
 			else
 			{
 				let tmpBinding = this._AffinityBindings[tmpWorkItem.AffinityKey];
@@ -1275,23 +1288,101 @@ class UltravisorBeaconCoordinator extends libPictService
 		}
 		else if (tmpWorkItem.Status === 'Assigned' && tmpWorkItem.AssignedBeaconID && this._WorkItemPushHandler)
 		{
-			// Affinity pre-assigned — push directly to the assigned beacon via WebSocket
-			tmpWorkItem.Status = 'Running';
-			let tmpPushed = this._WorkItemPushHandler(tmpWorkItem.AssignedBeaconID,
-				this._sanitizeWorkItemForBeacon(tmpWorkItem));
+			// Affinity pre-assigned — push directly to the assigned beacon via
+			// WebSocket, but only within the beacon's RUNNING capacity. The
+			// beacon SDK silently drops frames beyond its concurrency, so an
+			// ungated burst loses work items (they sit "Running" until the
+			// direct-dispatch timeout while the beacon never saw them).
+			// Over-capacity items stay Assigned; the slot-free re-dispatch in
+			// _dispatchPendingWorkItems delivers them as completions land.
+			this._pushAssignedWorkItem(tmpWorkItem);
+		}
 
-			if (tmpPushed)
-			{
-				this.log.info(`BeaconCoordinator: pushed affinity-assigned work item [${tmpWorkItemHash}] to WebSocket beacon [${tmpWorkItem.AssignedBeaconID}].`);
-			}
-			else
+		return tmpWorkItem;
+	}
+
+	/**
+	 * Push an Assigned work item to its designated WebSocket beacon when the
+	 * beacon has Running capacity. Leaves the item Assigned (HTTP-poll
+	 * claimable, slot-free re-deliverable) when the beacon is full, offline,
+	 * or the push fails.
+	 *
+	 * @param {object} pWorkItem
+	 * @returns {boolean} True when the item was delivered.
+	 */
+	_pushAssignedWorkItem(pWorkItem)
+	{
+		if (!this._WorkItemPushHandler || !pWorkItem.AssignedBeaconID)
+		{
+			return false;
+		}
+		let tmpBeacon = this._Beacons[pWorkItem.AssignedBeaconID];
+		if (!tmpBeacon || (tmpBeacon.Status !== 'Online' && tmpBeacon.Status !== 'Busy'))
+		{
+			return false;
+		}
+		let tmpMaxConcurrent = tmpBeacon.MaxConcurrent || 1;
+		if (this._runningCountForBeacon(pWorkItem.AssignedBeaconID) >= tmpMaxConcurrent)
+		{
+			this.log.info(`BeaconCoordinator: beacon [${pWorkItem.AssignedBeaconID}] at running capacity (${tmpMaxConcurrent}) — holding assigned work item [${pWorkItem.WorkItemHash}] for slot-free delivery.`);
+			return false;
+		}
+		pWorkItem.Status = 'Running';
+		let tmpPushed = this._WorkItemPushHandler(pWorkItem.AssignedBeaconID,
+			this._sanitizeWorkItemForBeacon(pWorkItem));
+		if (tmpPushed)
+		{
+			this.log.info(`BeaconCoordinator: pushed affinity-assigned work item [${pWorkItem.WorkItemHash}] to WebSocket beacon [${pWorkItem.AssignedBeaconID}].`);
+			return true;
+		}
+		pWorkItem.Status = 'Assigned';
+		return false;
+	}
+
+	/**
+	 * Count work items currently RUNNING on a beacon. CurrentWorkItems
+	 * includes Assigned-but-not-yet-delivered items, so it overstates the
+	 * beacon's true in-flight load — pushes must be gated on Running only,
+	 * or a burst of affinity-assigned items overruns the beacon SDK's
+	 * concurrency and the overflow frames are silently dropped.
+	 *
+	 * @param {string} pBeaconID
+	 * @returns {number}
+	 */
+	_runningCountForBeacon(pBeaconID)
+	{
+		let tmpCount = 0;
+		let tmpHashes = Object.keys(this._WorkQueue);
+		for (let i = 0; i < tmpHashes.length; i++)
+		{
+			let tmpWI = this._WorkQueue[tmpHashes[i]];
+			if (tmpWI && tmpWI.AssignedBeaconID === pBeaconID && tmpWI.Status === 'Running')
 			{
-				// WebSocket push failed — revert to Assigned for HTTP poll pickup
-				tmpWorkItem.Status = 'Assigned';
+				tmpCount++;
 			}
 		}
+		return tmpCount;
+	}
 
-		return tmpWorkItem;
+	/**
+	 * Whether a beacon is allowed to take a work item under affinity rules.
+	 *
+	 * RequireAffinityMatch items designate a beacon BY NAME: only that beacon
+	 * may be pushed, polled, or sticky-bound the item. Without the flag,
+	 * AffinityKey keeps its dual role (name routing when matched, otherwise a
+	 * session-stickiness hint any capable beacon can seed).
+	 *
+	 * @param {object} pWorkItem
+	 * @param {object} pBeacon - a registered beacon record
+	 * @returns {boolean}
+	 */
+	_beaconSatisfiesAffinity(pWorkItem, pBeacon)
+	{
+		if (!pWorkItem || !pWorkItem.RequireAffinityMatch || !pWorkItem.AffinityKey)
+		{
+			return true;
+		}
+		return !!(pBeacon && pBeacon.Name === pWorkItem.AffinityKey);
 	}
 
 	/**
@@ -1328,6 +1419,11 @@ class UltravisorBeaconCoordinator extends libPictService
 			{
 				continue;
 			}
+			if (!this._beaconSatisfiesAffinity(pWorkItem, tmpBeacon))
+			{
+				continue;
+			}
+
 			if (tmpBeacon.Capabilities.indexOf(pWorkItem.Capability) === -1)
 			{
 				continue;
@@ -1527,6 +1623,12 @@ class UltravisorBeaconCoordinator extends libPictService
 				continue;
 			}
 
+			// Strict affinity: only the designated beacon may claim
+			if (!this._beaconSatisfiesAffinity(tmpWorkItem, tmpBeacon))
+			{
+				continue;
+			}
+
 			// Check capability match
 			if (tmpBeacon.Capabilities.indexOf(tmpWorkItem.Capability) === -1)
 			{
@@ -2089,7 +2191,9 @@ class UltravisorBeaconCoordinator extends libPictService
 			{
 				if (tmpContext.WaitingTasks[tmpWorkItem.NodeHash])
 				{
-					tmpContext.WaitingTasks[tmpWorkItem.NodeHash].ResumeEventName = 'error';
+					// Must exactly match the EventOutputs Name 'Error' — the engine's
+					// downstream-event match is case-sensitive.
+					tmpContext.WaitingTasks[tmpWorkItem.NodeHash].ResumeEventName = 'Error';
 				}
 				// Push the failure into the canonical Errors[] log so
 				// finalizeExecution's roll-up sees it and the operation
@@ -2668,6 +2772,13 @@ class UltravisorBeaconCoordinator extends libPictService
 		{
 			let tmpWI = this._WorkQueue[tmpHashes[i]];
 			if (!tmpWI) continue;
+			if (tmpWI.Status === 'Assigned' && tmpWI.AssignedBeaconID)
+			{
+				// Held back at enqueue because the designated beacon was at
+				// running capacity — deliver as slots free up.
+				this._pushAssignedWorkItem(tmpWI);
+				continue;
+			}
 			if (tmpWI.Status !== 'Pending') continue;
 			if (tmpWI.AssignedBeaconID) continue; // affinity-assigned, leave it
 			this._tryPushToWebSocketBeacon(tmpWI);

package/source/services/Ultravisor-ExecutionEngine.cjs

@@ -1541,6 +1541,7 @@ class UltravisorExecutionEngine extends libPictService
 		let tmpConnections = pContext._ConnectionMap.eventSources[pSourceNodeHash] || [];
 		let tmpPortLabelMap = pContext._PortLabelMap;
 
+		let tmpMatchedCount = 0;
 		for (let i = 0; i < tmpConnections.length; i++)
 		{
 			let tmpConn = tmpConnections[i];
@@ -1548,6 +1549,7 @@ class UltravisorExecutionEngine extends libPictService
 
 			if (tmpSourcePortName === pEventName)
 			{
+				tmpMatchedCount++;
 				let tmpTargetPortName = this._extractPortName(tmpConn.TargetPortHash, tmpPortLabelMap);
 				pContext.PendingEvents.push({
 					TargetNodeHash: tmpConn.TargetNodeHash,
@@ -1555,6 +1557,14 @@ class UltravisorExecutionEngine extends libPictService
 				});
 			}
 		}
+
+		// An event that matches none of the node's outgoing connections strands
+		// everything downstream while the run can still terminate 'Complete' —
+		// surface it (event-name/port-label matching is case-sensitive).
+		if (tmpConnections.length > 0 && tmpMatchedCount === 0)
+		{
+			this._log(pContext, `Node [${pSourceNodeHash}] fired event [${pEventName}] but none of its ${tmpConnections.length} outgoing event connection(s) match that name — downstream nodes will not run.`, 'warn');
+		}
 	}
 
 	/**

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

@@ -421,7 +421,17 @@ module.exports =
 			{
 				try
 				{
-					tmpResult = pTask.fable.ExpressionParser.resolve(tmpExpression, pExecutionContext);
+					// Fable's ExpressionParser API is solve(expression, dataSource,
+					// results, manifest, destination). The data source mirrors the
+					// StateManager address roots so expressions can reference
+					// Operation.X / Global.X / TaskOutput.<node>.<key> directly.
+					tmpResult = pTask.fable.ExpressionParser.solve(tmpExpression,
+						{
+							Operation: pExecutionContext.OperationState || {},
+							Global: pExecutionContext.GlobalState || {},
+							TaskOutput: pExecutionContext.TaskOutputs || {}
+						},
+						{}, pTask.fable.manifest, {});
 				}
 				catch (pError)
 				{

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

@@ -131,10 +131,13 @@ module.exports =
 			pTask.log.info(`Beacon Dispatch: enqueued work item [${tmpWorkItem.WorkItemHash}] for capability [${tmpWorkItemInfo.Capability}/${tmpWorkItemInfo.Action}]` +
 				(tmpWorkItemInfo.AffinityKey ? ` with affinity [${tmpWorkItemInfo.AffinityKey}]` : ''));
 
-			// Pause execution — the BeaconCoordinator will call resumeOperation when the Beacon reports back
+			// Pause execution — the BeaconCoordinator will call resumeOperation when the Beacon reports back.
+			// ResumeEventName must exactly match an EventOutputs Name ('Complete') — the
+			// engine's downstream-event match is case-sensitive, so 'complete' silently
+			// strands every node wired after this one.
 			return fCallback(null, {
 				WaitingForInput: true,
-				ResumeEventName: 'complete',
+				ResumeEventName: 'Complete',
 				PromptMessage: `Waiting for Beacon worker (${tmpWorkItemInfo.Capability}/${tmpWorkItemInfo.Action})`,
 				OutputAddress: '',
 				Outputs: {},

package/source/services/tasks/flow-control/Ultravisor-TaskConfigs-FlowControl.cjs

@@ -211,7 +211,21 @@ module.exports =
 				{
 					if (pTask.fable.ExpressionParser)
 					{
-						tmpResult = pTask.fable.ExpressionParser.resolve(pResolvedSettings.Expression, pExecutionContext);
+						// Fable's ExpressionParser API is solve(expression, dataSource,
+						// results, manifest, destination); the data source mirrors the
+						// StateManager address roots. solve returns STRINGS — boolean
+						// comparisons come back as '1'/'0', and '0' is truthy in JS,
+						// so coerce explicitly before branching.
+						let tmpSolved = pTask.fable.ExpressionParser.solve(pResolvedSettings.Expression,
+							{
+								Operation: pExecutionContext.OperationState || {},
+								Global: pExecutionContext.GlobalState || {},
+								TaskOutput: pExecutionContext.TaskOutputs || {}
+							},
+							{}, pTask.fable.manifest, {});
+						tmpResult = !(tmpSolved === undefined || tmpSolved === null || tmpSolved === false
+							|| tmpSolved === 0 || tmpSolved === '' || tmpSolved === '0'
+							|| String(tmpSolved).toLowerCase() === 'false');
 					}
 					else
 					{

package/source/services/tasks/flow-control/Ultravisor-TaskType-IfConditional.cjs

@@ -36,7 +36,21 @@ class UltravisorTaskTypeIfConditional extends libTaskTypeBase
 			{
 				if (this.fable.ExpressionParser)
 				{
-					tmpResult = this.fable.ExpressionParser.resolve(pResolvedSettings.Expression, pExecutionContext);
+					// Fable's ExpressionParser API is solve(expression, dataSource,
+					// results, manifest, destination); the data source mirrors the
+					// StateManager address roots. solve returns STRINGS — boolean
+					// comparisons come back as '1'/'0', and '0' is truthy in JS,
+					// so coerce explicitly before branching.
+					let tmpSolved = this.fable.ExpressionParser.solve(pResolvedSettings.Expression,
+						{
+							Operation: pExecutionContext.OperationState || {},
+							Global: pExecutionContext.GlobalState || {},
+							TaskOutput: pExecutionContext.TaskOutputs || {}
+						},
+						{}, this.fable.manifest, {});
+					tmpResult = !(tmpSolved === undefined || tmpSolved === null || tmpSolved === false
+						|| tmpSolved === 0 || tmpSolved === '' || tmpSolved === '0'
+						|| String(tmpSolved).toLowerCase() === 'false');
 				}
 				else
 				{

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

@@ -106,7 +106,7 @@ module.exports =
 				if (tmpExistingValue !== undefined && tmpExistingValue !== null && tmpExistingValue !== '')
 				{
 					return fCallback(null, {
-						EventToFire: 'complete',
+						EventToFire: 'ValueInputComplete',
 						Outputs: { InputValue: tmpExistingValue },
 						Log: [`Auto-resolved from pre-seeded state: "${tmpOutputAddress}" = "${String(tmpExistingValue).substring(0, 100)}"`]
 					});
@@ -123,7 +123,7 @@ module.exports =
 			if (tmpIsProgrammatic && tmpDefaultValue !== undefined && tmpDefaultValue !== null && tmpDefaultValue !== '')
 			{
 				return fCallback(null, {
-					EventToFire: 'complete',
+					EventToFire: 'ValueInputComplete',
 					Outputs: { InputValue: tmpDefaultValue },
 					Log: [`Auto-resolved from default: "${tmpOutputAddress}" = "${String(tmpDefaultValue).substring(0, 100)}"`]
 				});
@@ -135,7 +135,7 @@ module.exports =
 			if (tmpIsProgrammatic && tmpIsOptional)
 			{
 				return fCallback(null, {
-					EventToFire: 'complete',
+					EventToFire: 'ValueInputComplete',
 					Outputs: { InputValue: '' },
 					Log: [`Auto-resolved optional field: "${tmpOutputAddress}" = "" (no value provided)`]
 				});

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

@@ -41,7 +41,7 @@ class UltravisorTaskTypeValueInput extends libTaskTypeBase
 			if (tmpExistingValue !== undefined && tmpExistingValue !== null && tmpExistingValue !== '')
 			{
 				return fCallback(null, {
-					EventToFire: 'complete',
+					EventToFire: 'ValueInputComplete',
 					Outputs: { InputValue: tmpExistingValue },
 					Log: [`Auto-resolved from pre-seeded state: "${tmpOutputAddress}" = "${String(tmpExistingValue).substring(0, 100)}"`]
 				});
@@ -59,7 +59,7 @@ class UltravisorTaskTypeValueInput extends libTaskTypeBase
 		if (tmpIsProgrammatic && tmpDefaultValue !== undefined && tmpDefaultValue !== null && tmpDefaultValue !== '')
 		{
 			return fCallback(null, {
-				EventToFire: 'complete',
+				EventToFire: 'ValueInputComplete',
 				Outputs: { InputValue: tmpDefaultValue },
 				Log: [`Auto-resolved from default: "${tmpOutputAddress}" = "${String(tmpDefaultValue).substring(0, 100)}"`]
 			});
@@ -71,7 +71,7 @@ class UltravisorTaskTypeValueInput extends libTaskTypeBase
 		if (tmpIsProgrammatic && tmpIsOptional)
 		{
 			return fCallback(null, {
-				EventToFire: 'complete',
+				EventToFire: 'ValueInputComplete',
 				Outputs: { InputValue: '' },
 				Log: [`Auto-resolved optional field: "${tmpOutputAddress}" = "" (no value provided)`]
 			});