Update factory/world_factory.py

factory/world_factory.py

@@ -18,23 +18,13 @@ Typical pipeline:
         -> WorldFactory
         -> World
 
-Example:
-    from dsl.parser import parse_world_file
-    from factory.world_factory import WorldFactory
-
-    spec = parse_world_file("examples/research.json")
-    world = WorldFactory().create_world(spec)
-
-    for _ in range(spec.simulation.steps):
-        world.step()
-
-Future extensibility:
-    - Add plugin package discovery for external behavior registries.
-    - Add metric object instantiation once metrics registries are available.
-    - Add migration-aware factory profiles for schema versions.
-    - Add object pooling for large simulations.
-    - Add dependency injection hooks for testing.
-    - Add richer event adapters and world-level event buses.
+Important runtime compatibility notes:
+    - DSL positions are JSON arrays, but runtime World/Agent/Resource code may
+      expect NumPy arrays with attributes such as ``.size``.
+    - This factory converts all runtime agent/resource positions to NumPy arrays.
+    - Behavior ids are runtime details and are injected automatically.
+    - Agent behavior storage is provided as a mapping keyed by deterministic
+      behavior ids.
 """
 
 from __future__ import annotations
@@ -42,13 +32,14 @@ from __future__ import annotations
 import copy
 import inspect
 import logging
-import numpy as np
-from collections.abc import Mapping, MutableMapping, Sequence
+from collections.abc import Mapping, Sequence
 from dataclasses import dataclass, field
 from importlib import import_module
 from types import MappingProxyType
 from typing import Any
 
+import numpy as np
+
 from core.agent import Agent
 from core.behavior import Behavior
 from core.event import Event
@@ -72,8 +63,10 @@ from dsl.validator import (
 )
 from policies.base_policy import BasePolicy
 
+
 logger = logging.getLogger(__name__)
 
+
 DEFAULT_BEHAVIOR_MODULES: tuple[str, ...] = (
     "behaviors.movement",
     "behaviors.consume",
@@ -96,6 +89,7 @@ DEFAULT_POLICY_MODULES: tuple[str, ...] = (
 )
 
 BEHAVIOR_REGISTRY_ATTRIBUTES: tuple[str, ...] = ("BEHAVIOR_REGISTRY",)
+
 POLICY_REGISTRY_ATTRIBUTES: tuple[str, ...] = (
     "POLICY_REGISTRY",
     "RULE_POLICY_REGISTRY",
@@ -126,6 +120,7 @@ _CORE_EVENT_ALIASES: Mapping[str, tuple[str, ...]] = MappingProxyType(
 )
 
 _CORE_WORLD_ALIASES: Mapping[str, tuple[str, ...]] = MappingProxyType({})
+
 _CORE_SCHEDULER_ALIASES: Mapping[str, tuple[str, ...]] = MappingProxyType({})
 
 
@@ -229,24 +224,7 @@ class WorldBuildResult:
 
 @dataclass
 class WorldFactoryConfig:
-    """Configuration for ``WorldFactory``.
-
-    Attributes:
-        validate_before_build: Run semantic DSL validation before construction.
-        strict_unknown_behaviors: Raise if a behavior name is not registered.
-        strict_unknown_policies: Raise if a policy type is not registered.
-        strict_constructor_params: Raise on constructor parameters not accepted
-            by the runtime class.
-        include_disabled_behaviors: Instantiate behaviors marked disabled.
-        include_disabled_events: Instantiate events marked disabled.
-        attach_default_policy: Attach a default policy to agents that define
-            behaviors but omit a policy.
-        default_policy_type: Default policy registry key.
-        attach_scheduler: Attach a scheduler instance to the world when
-            possible.
-        attach_dsl_spec_to_world: Store the validated ``WorldSpec`` on the
-            runtime world for diagnostics and UI use.
-    """
+    """Configuration for ``WorldFactory``."""
 
     validate_before_build: bool = True
 
@@ -280,12 +258,7 @@ class WorldFactoryConfig:
 
 @dataclass
 class GenericScheduledEvent:
-    """Fallback event object used when ``core.event.Event`` is not instantiable.
-
-    The adapter keeps event records executable and inspectable without imposing
-    domain-specific event semantics. It returns its payload when executed.
-    Future event-system modules can replace this with richer event dispatch.
-    """
+    """Fallback event object used when ``core.event.Event`` is not instantiable."""
 
     name: str
     trigger_step: int
@@ -298,12 +271,7 @@ class GenericScheduledEvent:
     metadata: Mapping[str, Any] = field(default_factory=dict)
 
     def execute(self, world: World) -> dict[str, Any]:
-        """Execute the event in a domain-agnostic way.
-
-        The fallback adapter does not mutate world state by default. It returns
-        a structured event outcome that schedulers, logs, metrics, or narrators
-        can consume.
-        """
+        """Execute the event in a domain-agnostic way."""
 
         return {
             "event": self.name,
@@ -319,12 +287,7 @@ class GenericScheduledEvent:
 
 @dataclass
 class WorldFactory:
-    """Factory that converts ``WorldSpec`` into a runtime ``World``.
-
-    The factory owns behavior and policy registries. Registries may come from
-    default behavior/policy modules or from custom mappings supplied through
-    ``WorldFactoryConfig``.
-    """
+    """Factory that converts ``WorldSpec`` into a runtime ``World``."""
 
     config: WorldFactoryConfig = field(default_factory=WorldFactoryConfig)
 
@@ -355,69 +318,9 @@ class WorldFactory:
         """Return registry import errors collected during initialization."""
 
         return MappingProxyType(self._registry_import_errors)
-    
-    @staticmethod
-    def _behavior_runtime_id(
-        spec: BehaviorSpec,
-        *,
-        owner_agent_id: str | None,
-        behavior_index: int | None,
-    ) -> str:
-        """Return a deterministic runtime id for a behavior spec."""
-
-        metadata_id = None
-        if isinstance(spec.metadata, Mapping):
-            metadata_id = spec.metadata.get("id") or spec.metadata.get("behavior_id")
-
-        if metadata_id is not None and str(metadata_id).strip():
-            return str(metadata_id).strip()
-
-        owner = owner_agent_id or "world"
-        index = 0 if behavior_index is None else int(behavior_index)
-        return f"{owner}:behavior:{index}:{spec.name}"
-    
-    @staticmethod
-    def _agent_runtime_position(position: Any) -> np.ndarray:
-        """Return a NumPy position vector compatible with core.agent.Agent.
-
-        The current Agent implementation expects position to behave like a NumPy
-        array. In particular, Agent.observe() and Agent.snapshot() use array-style
-        methods such as copy() and tolist().
-        """
-
-        if position is None:
-            return np.zeros(2, dtype=np.float64)
-
-        try:
-            array = np.asarray(position, dtype=np.float64).reshape(-1)
-        except (TypeError, ValueError) as exc:
-            raise RuntimeObjectBuildError(
-                f"Agent position must be numeric, got {position!r}"
-            ) from exc
-
-        if array.size == 0:
-            return np.zeros(2, dtype=np.float64)
-
-        if not np.all(np.isfinite(array)):
-            raise RuntimeObjectBuildError(
-                f"Agent position must contain only finite values, got {position!r}"
-            )
-
-        return array
 
     def create_world(self, spec: WorldSpec | Mapping[str, Any]) -> World:
-        """Create a runtime world from a validated or mappable world spec.
-
-        Args:
-            spec: ``WorldSpec`` or mapping that can validate into ``WorldSpec``.
-
-        Returns:
-            Runtime ``World`` object.
-
-        Raises:
-            WorldFactoryValidationError: If semantic validation fails.
-            WorldFactoryError: If runtime construction fails.
-        """
+        """Create a runtime world from a validated or mappable world spec."""
 
         return self.create_world_result(spec).world
 
@@ -427,14 +330,32 @@ class WorldFactory:
         world_spec = self._coerce_world_spec(spec)
         validation_report = self._validate_before_build(world_spec)
 
-        resources = tuple(self.create_resource(resource_spec) for resource_spec in world_spec.resources)
+        space_dimensions = (
+            int(world_spec.space.dimensions)
+            if world_spec.space is not None
+            else None
+        )
+
+        resources = tuple(
+            self.create_resource(resource_spec, dimensions=space_dimensions)
+            for resource_spec in world_spec.resources
+        )
+
         events = tuple(
             self.create_event(event_spec)
             for event_spec in world_spec.events
             if event_spec.enabled or self.config.include_disabled_events
         )
-        agents = tuple(self.create_agent(agent_spec) for agent_spec in world_spec.agents)
-        metrics = tuple(self.create_metric_config(metric_spec) for metric_spec in world_spec.metrics)
+
+        agents = tuple(
+            self.create_agent(agent_spec, dimensions=space_dimensions)
+            for agent_spec in world_spec.agents
+        )
+
+        metrics = tuple(
+            self.create_metric_config(metric_spec)
+            for metric_spec in world_spec.metrics
+        )
 
         world = self._create_world_object(
             spec=world_spec,
@@ -475,32 +396,59 @@ class WorldFactory:
 
         return WorldBuildResult(world=world, report=report)
 
-    def create_agent(self, spec: AgentSpec) -> Agent:
+    def create_agent(
+        self,
+        spec: AgentSpec,
+        *,
+        dimensions: int | None = None,
+    ) -> Agent:
         """Create a runtime ``Agent`` from an ``AgentSpec``."""
 
-        behaviors = tuple(
-            self.create_behavior(
+        behavior_map: dict[str, Behavior] = {}
+
+        for behavior_index, behavior_spec in enumerate(spec.behaviors):
+            if not behavior_spec.enabled and not self.config.include_disabled_behaviors:
+                continue
+
+            behavior = self.create_behavior(
                 behavior_spec,
                 owner_agent_id=spec.id,
                 behavior_index=behavior_index,
             )
-            for behavior_index, behavior_spec in enumerate(spec.behaviors)
-            if behavior_spec.enabled or self.config.include_disabled_behaviors
-        )
+
+            behavior_id = str(
+                getattr(behavior, "id", "")
+                or self._behavior_runtime_id(
+                    behavior_spec,
+                    owner_agent_id=spec.id,
+                    behavior_index=behavior_index,
+                )
+            )
+
+            if behavior_id in behavior_map:
+                behavior_id = f"{behavior_id}#{behavior_index}"
+
+            behavior_map[behavior_id] = behavior
+
         policy = self.create_policy_for_agent(spec)
 
-        runtime_position = self._agent_runtime_position(spec.position)
+        runtime_position = self._agent_runtime_position(
+            spec.position,
+            dimensions=dimensions,
+        )
 
         params = {
             "id": spec.id,
             "type": spec.type,
-            "position": runtime_position,
+            "position": runtime_position.copy(),
             "state": copy.deepcopy(spec.state),
             "memory": copy.deepcopy(spec.memory),
             "goals": copy.deepcopy(spec.goals),
-            "behaviors": behaviors,
+            "behaviors": behavior_map,
             "policy": policy,
             "alive": bool(spec.alive),
+            "metadata": copy.deepcopy(spec.metadata),
+            "dsl_spec": spec,
         }
 
         agent = self._instantiate_runtime_object(
@@ -514,16 +462,17 @@ class WorldFactory:
 
         self._safe_setattr(agent, "id", spec.id)
         self._safe_setattr(agent, "type", spec.type)
-        self._safe_setattr(agent, "position", runtime_position.copy())
+        self._force_setattr(agent, "position", runtime_position.copy())
         self._safe_setattr(agent, "state", copy.deepcopy(spec.state))
         self._safe_setattr(agent, "memory", copy.deepcopy(spec.memory))
         self._safe_setattr(agent, "goals", copy.deepcopy(spec.goals))
-        self._safe_setattr(agent, "behaviors", behaviors)
+        self._safe_setattr(agent, "behaviors", behavior_map)
         self._safe_setattr(agent, "policy", policy)
         self._safe_setattr(agent, "alive", bool(spec.alive))
         self._safe_setattr(agent, "metadata", copy.deepcopy(spec.metadata))
         self._safe_setattr(agent, "dsl_spec", spec)
 
+        self._ensure_agent_position_array(agent, dimensions=dimensions)
         return agent
 
     def create_behavior(
@@ -533,12 +482,7 @@ class WorldFactory:
         owner_agent_id: str | None = None,
         behavior_index: int | None = None,
     ) -> Behavior:
-        """Create a runtime behavior object from a ``BehaviorSpec``.
-
-        The DSL does not require behavior ids because behavior specs are declarative.
-        Runtime ids are injected here so behavior base classes that require ``id``
-        can still be instantiated safely and deterministically.
-        """
+        """Create a runtime behavior object from a ``BehaviorSpec``."""
 
         target = self._resolve_registry_item(
             registry=self._behavior_registry,
@@ -555,9 +499,6 @@ class WorldFactory:
         )
 
         params = copy.deepcopy(spec.params)
-
-        # Runtime-injected fields. These are filtered out automatically if the
-        # concrete behavior constructor does not accept them.
         params.setdefault("id", runtime_behavior_id)
         params.setdefault("behavior_id", runtime_behavior_id)
         params.setdefault("name", spec.name)
@@ -587,11 +528,7 @@ class WorldFactory:
         return behavior
 
     def create_policy_for_agent(self, agent_spec: AgentSpec) -> BasePolicy | None:
-        """Create the policy configured for an agent.
-
-        If the agent has behaviors but omits a policy, the factory may attach a
-        default policy depending on configuration.
-        """
+        """Create the policy configured for an agent."""
 
         policy_spec = agent_spec.policy
 
@@ -616,6 +553,7 @@ class WorldFactory:
 
         params = copy.deepcopy(spec.params)
         params.setdefault("enabled", bool(spec.enabled))
+
         if spec.metadata:
             params.setdefault("metadata", copy.deepcopy(spec.metadata))
 
@@ -639,21 +577,32 @@ class WorldFactory:
 
         return policy
 
-    def create_resource(self, spec: ResourceSpec) -> Resource:
+    def create_resource(
+        self,
+        spec: ResourceSpec,
+        *,
+        dimensions: int | None = None,
+    ) -> Resource:
         """Create a runtime ``Resource`` from a ``ResourceSpec``."""
 
         metadata = copy.deepcopy(spec.metadata)
         metadata.setdefault("regeneration_rate", spec.regeneration_rate)
         metadata.setdefault("max_amount", spec.max_amount)
 
+        runtime_position = self._resource_runtime_position(
+            spec.position,
+            dimensions=dimensions,
+        )
+
         params = {
             "id": spec.id,
             "type": spec.type,
             "amount": float(spec.amount),
-            "position": None if spec.position is None else tuple(spec.position),
+            "position": runtime_position.copy(),
             "metadata": metadata,
             "regeneration_rate": float(spec.regeneration_rate),
             "max_amount": spec.max_amount,
+            "dsl_spec": spec,
         }
 
         resource = self._instantiate_runtime_object(
@@ -668,12 +617,13 @@ class WorldFactory:
         self._safe_setattr(resource, "id", spec.id)
         self._safe_setattr(resource, "type", spec.type)
         self._safe_setattr(resource, "amount", float(spec.amount))
-        self._safe_setattr(resource, "position", None if spec.position is None else tuple(spec.position))
+        self._force_setattr(resource, "position", runtime_position.copy())
         self._safe_setattr(resource, "metadata", metadata)
         self._safe_setattr(resource, "regeneration_rate", float(spec.regeneration_rate))
         self._safe_setattr(resource, "max_amount", spec.max_amount)
         self._safe_setattr(resource, "dsl_spec", spec)
 
+        self._ensure_resource_position_array(resource, dimensions=dimensions)
         return resource
 
     def create_event(self, spec: EventSpec) -> Event | GenericScheduledEvent:
@@ -728,12 +678,7 @@ class WorldFactory:
         return event
 
     def create_metric_config(self, spec: MetricSpec) -> dict[str, Any]:
-        """Create a metric configuration record.
-
-        Metric runtime classes are introduced later in the implementation
-        order. Until then, metric specs are preserved as serializable records on
-        the world.
-        """
+        """Create a metric configuration record."""
 
         return {
             "name": spec.name,
@@ -753,12 +698,13 @@ class WorldFactory:
     ) -> World:
         """Instantiate and populate the runtime world object."""
 
-        agent_collection: Mapping[str, Agent] | tuple[Agent, ...]
-        resource_collection: Mapping[str, Resource] | tuple[Resource, ...]
-
         if self.config.world_uses_mapping_collections:
-            agent_collection = {str(getattr(agent, "id")): agent for agent in agents}
-            resource_collection = {str(getattr(resource, "id")): resource for resource in resources}
+            agent_collection: Mapping[str, Agent] | tuple[Agent, ...] = {
+                str(getattr(agent, "id")): agent for agent in agents
+            }
+            resource_collection: Mapping[str, Resource] | tuple[Resource, ...] = {
+                str(getattr(resource, "id")): resource for resource in resources
+            }
         else:
             agent_collection = tuple(agents)
             resource_collection = tuple(resources)
@@ -775,6 +721,7 @@ class WorldFactory:
             "events": tuple(events),
             "metrics": metric_collection,
             "step_count": 0,
+            "metadata": copy.deepcopy(spec.metadata),
         }
 
         try:
@@ -790,9 +737,14 @@ class WorldFactory:
             logger.debug("Falling back to no-argument World constructor", exc_info=True)
             world = self.config.world_class()
 
+        # Attach metadata before installation so World.add_agent/add_resource can
+        # see space/dimension configuration if the World implementation uses it.
+        self._attach_world_metadata(world, spec)
+
         self._install_agents(world, agents)
         self._install_resources(world, resources)
         self._install_events(world, events)
+
         self._safe_setattr(world, "metrics", metric_collection)
         self._safe_setattr(world, "step_count", 0)
 
@@ -807,14 +759,24 @@ class WorldFactory:
             self._safe_setattr(world, "agents", [])
 
         add_agent = getattr(world, "add_agent", None)
+
         if callable(add_agent):
             for agent in agents:
+                self._ensure_agent_position_array(agent)
                 add_agent(agent)
             return
 
         if self.config.world_uses_mapping_collections:
-            self._safe_setattr(world, "agents", {str(getattr(agent, "id")): agent for agent in agents})
+            for agent in agents:
+                self._ensure_agent_position_array(agent)
+            self._safe_setattr(
+                world,
+                "agents",
+                {str(getattr(agent, "id")): agent for agent in agents},
+            )
         else:
+            for agent in agents:
+                self._ensure_agent_position_array(agent)
             self._safe_setattr(world, "agents", list(agents))
 
     def _install_resources(self, world: World, resources: Sequence[Resource]) -> None:
@@ -826,18 +788,24 @@ class WorldFactory:
             self._safe_setattr(world, "resources", [])
 
         add_resource = getattr(world, "add_resource", None)
+
         if callable(add_resource):
             for resource in resources:
+                self._ensure_resource_position_array(resource)
                 add_resource(resource)
             return
 
         if self.config.world_uses_mapping_collections:
+            for resource in resources:
+                self._ensure_resource_position_array(resource)
             self._safe_setattr(
                 world,
                 "resources",
                 {str(getattr(resource, "id")): resource for resource in resources},
             )
         else:
+            for resource in resources:
+                self._ensure_resource_position_array(resource)
             self._safe_setattr(world, "resources", list(resources))
 
     def _install_events(
@@ -850,6 +818,7 @@ class WorldFactory:
         self._safe_setattr(world, "events", [])
 
         add_event = getattr(world, "add_event", None)
+
         if callable(add_event):
             for event in events:
                 add_event(event)
@@ -861,6 +830,7 @@ class WorldFactory:
         """Attach a scheduler to the world when a scheduler class is configured."""
 
         scheduler_class = self.config.scheduler_class
+
         if scheduler_class is None:
             return
 
@@ -903,6 +873,11 @@ class WorldFactory:
         self._safe_setattr(world, "space_config", None if spec.space is None else spec.space.to_dict())
         self._safe_setattr(world, "schema_version", spec.schema_version)
 
+        if spec.space is not None:
+            self._safe_setattr(world, "dimensions", int(spec.space.dimensions))
+            self._safe_setattr(world, "dimension", int(spec.space.dimensions))
+            self._safe_setattr(world, "space_dimensions", int(spec.space.dimensions))
+
         if self.config.attach_dsl_spec_to_world:
             self._safe_setattr(world, "dsl_spec", spec)
 
@@ -925,6 +900,7 @@ class WorldFactory:
             if self.config.strict_constructor_params
             else ValidationSeverity.WARNING,
         )
+
         report = validate_world_spec(spec, config=validation_config)
 
         if not report.is_valid:
@@ -957,7 +933,10 @@ class WorldFactory:
         self._registry_import_errors.update(module_report.import_errors)
 
         if self.config.behavior_registry is not None:
-            registry.update({str(key): value for key, value in self.config.behavior_registry.items()})
+            registry.update({
+                str(key): value
+                for key, value in self.config.behavior_registry.items()
+            })
 
         return self._with_class_aliases(registry)
 
@@ -975,7 +954,10 @@ class WorldFactory:
         self._registry_import_errors.update(module_report.import_errors)
 
         if self.config.policy_registry is not None:
-            registry.update({str(key): value for key, value in self.config.policy_registry.items()})
+            registry.update({
+                str(key): value
+                for key, value in self.config.policy_registry.items()
+            })
 
         return self._with_class_aliases(registry)
 
@@ -994,16 +976,21 @@ class WorldFactory:
         for module_name in module_names:
             try:
                 module = import_module(module_name)
-            except Exception as exc:  # pragma: no cover - defensive for user modules
+            except Exception as exc:
                 import_errors[str(module_name)] = f"{exc.__class__.__name__}: {exc}"
                 continue
 
             for attribute_name in registry_attributes:
                 raw_registry = getattr(module, attribute_name, None)
                 if isinstance(raw_registry, Mapping):
-                    registry.update({str(key): value for key, value in raw_registry.items()})
+                    registry.update({
+                        str(key): value
+                        for key, value in raw_registry.items()
+                    })
 
-            registry.update(self._discover_named_subclasses(module, base_class=base_class))
+            registry.update(
+                self._discover_named_subclasses(module, base_class=base_class)
+            )
 
         return RegistryLoadReport(registry=registry, import_errors=import_errors)
 
@@ -1084,7 +1071,11 @@ class WorldFactory:
             raise RegistryResolutionError(message)
 
         logger.warning(message)
-        return self._noop_behavior_factory(name) if item_kind == "behavior" else self._noop_policy_factory(name)
+
+        if item_kind == "behavior":
+            return self._noop_behavior_factory(name)
+
+        return self._noop_policy_factory(name)
 
     def _instantiate_runtime_object(
         self,
@@ -1162,6 +1153,7 @@ class WorldFactory:
                     break
 
         unknown_params = set(working.keys()) - allowed_params
+
         if unknown_params and strict:
             raise ConstructorBindingError(
                 f"Unknown constructor parameter(s) for {item_kind} at {path}: "
@@ -1175,6 +1167,7 @@ class WorldFactory:
         }
 
         missing_required = required_params - set(filtered.keys())
+
         if missing_required:
             raise ConstructorBindingError(
                 f"Missing required constructor parameter(s) for {item_kind} at {path}: "
@@ -1221,13 +1214,150 @@ class WorldFactory:
         return allowed_params, required_params, accepts_var_keyword
 
     @staticmethod
-    def _safe_setattr(instance: Any, name: str, value: Any) -> bool:
-        """Set an attribute defensively.
+    def _behavior_runtime_id(
+        spec: BehaviorSpec,
+        *,
+        owner_agent_id: str | None,
+        behavior_index: int | None,
+    ) -> str:
+        """Return a deterministic runtime id for a behavior spec."""
+
+        metadata_id = None
+
+        if isinstance(spec.metadata, Mapping):
+            metadata_id = spec.metadata.get("id") or spec.metadata.get("behavior_id")
+
+        if metadata_id is not None and str(metadata_id).strip():
+            return str(metadata_id).strip()
+
+        owner = owner_agent_id or "world"
+        index = 0 if behavior_index is None else int(behavior_index)
+        return f"{owner}:behavior:{index}:{spec.name}"
+
+    @staticmethod
+    def _agent_runtime_position(
+        position: Any,
+        *,
+        dimensions: int | None = None,
+    ) -> np.ndarray:
+        """Return a NumPy position vector compatible with runtime agents."""
+
+        return WorldFactory._runtime_position(
+            position,
+            dimensions=dimensions,
+            object_label="Agent",
+        )
 
-        Returns:
-            ``True`` if the attribute was set, otherwise ``False``.
+    @staticmethod
+    def _resource_runtime_position(
+        position: Any,
+        *,
+        dimensions: int | None = None,
+    ) -> np.ndarray:
+        """Return a NumPy position vector compatible with runtime resources."""
+
+        return WorldFactory._runtime_position(
+            position,
+            dimensions=dimensions,
+            object_label="Resource",
+        )
+
+    @staticmethod
+    def _runtime_position(
+        position: Any,
+        *,
+        dimensions: int | None = None,
+        object_label: str = "Object",
+    ) -> np.ndarray:
+        """Return a NumPy runtime position vector.
+
+        Runtime World implementations may validate positions with NumPy-style
+        attributes such as ``position.size``. Therefore positions must not be
+        tuples by the time objects are installed into the World.
         """
 
+        target_dimensions = (
+            int(dimensions)
+            if dimensions is not None and int(dimensions) > 0
+            else 2
+        )
+
+        if position is None:
+            return np.zeros(target_dimensions, dtype=np.float64)
+
+        try:
+            array = np.asarray(position, dtype=np.float64).reshape(-1)
+        except (TypeError, ValueError) as exc:
+            raise RuntimeObjectBuildError(
+                f"{object_label} position must be numeric, got {position!r}"
+            ) from exc
+
+        if array.size == 0:
+            return np.zeros(target_dimensions, dtype=np.float64)
+
+        if not np.all(np.isfinite(array)):
+            raise RuntimeObjectBuildError(
+                f"{object_label} position must contain only finite values, got {position!r}"
+            )
+
+        if int(array.size) != target_dimensions:
+            raise RuntimeObjectBuildError(
+                f"{object_label} position has {int(array.size)} dimension(s), "
+                f"but world space expects {target_dimensions}"
+            )
+
+        return array.astype(np.float64, copy=True)
+
+    def _ensure_agent_position_array(
+        self,
+        agent: Agent,
+        *,
+        dimensions: int | None = None,
+    ) -> None:
+        """Ensure agent.position is a NumPy array before adding it to World."""
+
+        raw_position = getattr(agent, "position", None)
+        runtime_position = self._agent_runtime_position(
+            raw_position,
+            dimensions=dimensions,
+        )
+        self._force_setattr(agent, "position", runtime_position.copy())
+
+        repaired_position = getattr(agent, "position", None)
+        if not hasattr(repaired_position, "size"):
+            raise RuntimeObjectBuildError(
+                "Agent.position could not be converted to a NumPy array before "
+                f"world installation. Agent={getattr(agent, 'id', None)!r}, "
+                f"position_type={type(repaired_position).__name__}"
+            )
+
+    def _ensure_resource_position_array(
+        self,
+        resource: Resource,
+        *,
+        dimensions: int | None = None,
+    ) -> None:
+        """Ensure resource.position is a NumPy array before adding it to World."""
+
+        raw_position = getattr(resource, "position", None)
+        runtime_position = self._resource_runtime_position(
+            raw_position,
+            dimensions=dimensions,
+        )
+        self._force_setattr(resource, "position", runtime_position.copy())
+
+        repaired_position = getattr(resource, "position", None)
+        if not hasattr(repaired_position, "size"):
+            raise RuntimeObjectBuildError(
+                "Resource.position could not be converted to a NumPy array before "
+                f"world installation. Resource={getattr(resource, 'id', None)!r}, "
+                f"position_type={type(repaired_position).__name__}"
+            )
+
+    @staticmethod
+    def _safe_setattr(instance: Any, name: str, value: Any) -> bool:
+        """Set an attribute defensively."""
+
         try:
             setattr(instance, name, value)
             return True
@@ -1240,6 +1370,24 @@ class WorldFactory:
             )
             return False
 
+    @staticmethod
+    def _force_setattr(instance: Any, name: str, value: Any) -> None:
+        """Set an attribute, using object.__setattr__ as a fallback."""
+
+        try:
+            setattr(instance, name, value)
+            return
+        except Exception:
+            pass
+
+        try:
+            object.__setattr__(instance, name, value)
+            return
+        except Exception as exc:
+            raise RuntimeObjectBuildError(
+                f"Could not set attribute {name!r} on {instance.__class__.__name__}"
+            ) from exc
+
     @staticmethod
     def _noop_behavior_factory(name: str) -> type[Behavior]:
         """Create a no-op behavior class for permissive unknown behavior mode."""