Update llm/world_generator.py

llm/world_generator.py

@@ -1,1419 +1,1302 @@
 """
-Natural language to WorldSmithAI DSL generation.
-
-This module converts user prompts into ``WorldSpec`` JSON. It is designed for
-root-level Hugging Face Spaces ``app.py`` usage and does not assume any
-``app/`` package or folder structure.
-
-The SLM's responsibility is strictly:
-    Natural language -> JSON DSL
-
-The SLM must not generate Python code. The deterministic Python engine consumes
-only validated ``WorldSpec`` objects.
-
-Example root-level app.py usage:
-    from llm.world_generator import generate_world_spec
+Runtime object factory for WorldSmithAI.
+
+This module converts validated DSL specifications into live runtime objects:
+World, Agent, Resource, Event, Behavior, Policy, and Scheduler instances.
+
+The factory is intentionally domain-agnostic. It does not know about sheep,
+wolves, farms, dragons, scientists, markets, civilizations, power grids,
+transport networks, or research ecosystems. It only resolves generic DSL
+records through registries and runtime constructors.
+
+Typical pipeline:
+    raw prompt
+        -> llm.world_generator
+        -> JSON DSL
+        -> dsl.parser
+        -> dsl.validator
+        -> WorldFactory
+        -> World
+
+Example:
+    from dsl.parser import parse_world_file
     from factory.world_factory import WorldFactory
 
-    def run(prompt: str):
-        spec = generate_world_spec(prompt)
-        world = WorldFactory().create_world(spec)
-        return spec.to_json_string(), world
+    spec = parse_world_file("examples/research.json")
+    world = WorldFactory().create_world(spec)
 
-Using a custom SLM client:
-    generator = WorldGenerator(client=my_client)
-    result = generator.generate("A research ecosystem with competing labs")
-    print(result.json_text)
+    for _ in range(spec.simulation.steps):
+        world.step()
 
 Future extensibility:
-    - Add first-class Hugging Face transformers adapters.
-    - Add constrained decoding when available.
-    - Add schema-version migrations.
-    - Add model-specific prompt profiles.
-    - Add automatic JSON repair loops.
-    - Add world-quality self-critique before factory construction.
+    - 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.
 """
 
 from __future__ import annotations
 
 import copy
 import inspect
-import json
 import logging
-import re
-from collections.abc import Callable, Mapping, Sequence
+from collections.abc import Mapping, MutableMapping, Sequence
 from dataclasses import dataclass, field
-from enum import Enum
-from typing import Any, Protocol, runtime_checkable
-
-from dsl.parser import DSLParseError, ParseResult, WorldDSLParser
+from importlib import import_module
+from types import MappingProxyType
+from typing import Any
+
+from core.agent import Agent
+from core.behavior import Behavior
+from core.event import Event
+from core.resource import Resource
+from core.scheduler import Scheduler
+from core.world import World
 from dsl.schema import (
     AgentSpec,
     BehaviorSpec,
     EventSpec,
+    MetricSpec,
     PolicySpec,
     ResourceSpec,
-    SimulationSpec,
-    SpaceSpec,
     WorldSpec,
 )
-from dsl.validator import ValidationConfig, ValidationReport, ValidationSeverity, validate_world_spec
+from dsl.validator import (
+    ValidationConfig,
+    ValidationReport,
+    ValidationSeverity,
+    validate_world_spec,
+)
+from policies.base_policy import BasePolicy
 
 logger = logging.getLogger(__name__)
 
+DEFAULT_BEHAVIOR_MODULES: tuple[str, ...] = (
+    "behaviors.movement",
+    "behaviors.consume",
+    "behaviors.trade",
+    "behaviors.attack",
+    "behaviors.research",
+    "behaviors.collaboration",
+    "behaviors.transport",
+    "behaviors.construction",
+    "behaviors.governance",
+    "behaviors.market",
+    "behaviors.adoption",
+    "behaviors.planning",
+    "behaviors.memory",
+)
+
+DEFAULT_POLICY_MODULES: tuple[str, ...] = (
+    "policies.rule_policy",
+    "policies.contextual_bandit",
+)
+
+BEHAVIOR_REGISTRY_ATTRIBUTES: tuple[str, ...] = ("BEHAVIOR_REGISTRY",)
+POLICY_REGISTRY_ATTRIBUTES: tuple[str, ...] = (
+    "POLICY_REGISTRY",
+    "RULE_POLICY_REGISTRY",
+)
 
-DEFAULT_SYSTEM_PROMPT = """
-You are WorldSmithAI's world DSL generator.
-
-Your only job is to convert a user's natural language description into a
-WorldSmithAI WorldSpec JSON object.
-
-Critical rules:
-- Output JSON only.
-- Do not include Markdown fences.
-- Do not include explanations.
-- Do not generate Python code.
-- Do not invent classes such as Sheep, Wolf, Scientist, Dragon, City, or Truck.
-- Use generic DSL entities: agents, resources, events, behaviors, policies.
-- Agents may have any imaginative type string, but the runtime object is still Agent.
-- Behaviors must be referenced by registry name.
-- Policies must be referenced by registry type.
-- Keep the world small enough for a lightweight Gradio demo.
-- Prefer 4 to 8 agents unless the user asks for more.
-- Prefer 2D positions when possible.
-- Include state, memory, goals, behaviors, and policy for each agent.
-- Use deterministic values and avoid randomness in the DSL.
-""".strip()
-
-
-WORLD_DSL_FORMAT_GUIDE = """
-Return one JSON object with this structure:
-
-{
-  "schema_version": "1.0",
-  "id": "short_world_id",
-  "name": "Human readable world name",
-  "description": "Short description",
-  "simulation": {
-    "steps": 50,
-    "seed": 0,
-    "scheduler": "sequential",
-    "activation": "sequential",
-    "collect_history": true
-  },
-  "space": {
-    "dimensions": 2,
-    "bounds": [[0, 10], [0, 10]],
-    "toroidal": false,
-    "enforce_bounds": true
-  },
-  "agents": [
+_CORE_AGENT_ALIASES: Mapping[str, tuple[str, ...]] = MappingProxyType(
     {
-      "id": "agent_1",
-      "type": "generic_type",
-      "position": [1, 1],
-      "state": {"energy": 10, "credits": 5},
-      "memory": {"known_options": {"cooperate": 1.0}},
-      "goals": [{"id": "survive", "importance": 1.0, "score": 1.0}],
-      "behaviors": [
-        {"name": "remember", "params": {"category": "observation", "content": {"note": "initial memory"}}},
-        {"name": "prioritize", "params": {}},
-        {"name": "choose_goal", "params": {}},
-        {"name": "communicate", "params": {"message": "status_update", "max_recipients": 1}},
-        {"name": "cooperate", "params": {"effort": 1.0}}
-      ],
-      "policy": {
-        "type": "rule_policy",
-        "params": {
-          "rules": [
-            {"behavior_name": "choose_goal", "score_delta": 3.0},
-            {"behavior_name": "communicate", "score_delta": 1.0}
-          ]
-        }
-      },
-      "alive": true,
-      "metadata": {}
+        "id": ("agent_id",),
+        "type": ("agent_type", "kind"),
     }
-  ],
-  "resources": [
+)
+
+_CORE_RESOURCE_ALIASES: Mapping[str, tuple[str, ...]] = MappingProxyType(
     {
-      "id": "resource_1",
-      "type": "generic_resource",
-      "amount": 10,
-      "position": [5, 5],
-      "regeneration_rate": 0,
-      "max_amount": 20,
-      "metadata": {}
+        "id": ("resource_id",),
+        "type": ("resource_type", "kind"),
+        "amount": ("quantity",),
     }
-  ],
-  "events": [],
-  "metrics": [
-    {"name": "diversity", "params": {"collection": "agents", "group_by_path": "type"}}
-  ],
-  "metadata": {}
-}
-
-Known behavior names available in this project include:
-move, wander, seek, flee,
-eat, harvest, mine, collect,
-buy, sell, exchange,
-attack, defend, raid,
-study, publish, learn,
-cooperate, communicate, share, recommend, negotiate,
-route, deliver, ship, queue, charge,
-build, repair, expand, demolish,
-regulate, tax, subsidize, litigate, approve, enforce,
-bid, ask, price, discount, forecast, rebalance,
-adopt, switch, imitate, abandon, evaluate,
-prioritize, schedule, allocate_time, choose_goal,
-remember, forget, reinforce, update_belief.
-
-Known policy types include:
-rule_policy, contextual_bandit.
-""".strip()
-
-
-DEFAULT_MINIMAL_EXAMPLE = {
-    "schema_version": "1.0",
-    "id": "tiny_research_world",
-    "name": "Tiny Research World",
-    "description": "A small generic research ecosystem.",
-    "simulation": {
-        "steps": 40,
-        "seed": 0,
-        "scheduler": "sequential",
-        "activation": "sequential",
-        "collect_history": True,
-    },
-    "space": {
-        "dimensions": 2,
-        "bounds": [[0, 10], [0, 10]],
-        "toroidal": False,
-        "enforce_bounds": True,
-    },
-    "agents": [
-        {
-            "id": "scientist_1",
-            "type": "scientist",
-            "position": [1, 1],
-            "state": {"energy": 10, "credits": 5, "knowledge": 1},
-            "memory": {"known_options": {"study": 1.0, "communicate": 0.5}},
-            "goals": [{"id": "discover", "importance": 2.0, "score": 2.0}],
-            "behaviors": [
-                {
-                    "name": "remember",
-                    "params": {
-                        "category": "observation",
-                        "content": {"note": "initial research context"},
-                    },
-                },
-                {"name": "prioritize", "params": {}},
-                {"name": "choose_goal", "params": {}},
-                {"name": "communicate", "params": {"message": "research_update"}},
-                {"name": "cooperate", "params": {"goal": "discover", "effort": 1.0}},
-            ],
-            "policy": {
-                "type": "rule_policy",
-                "params": {
-                    "rules": [
-                        {"behavior_name": "choose_goal", "score_delta": 3.0},
-                        {"behavior_name": "communicate", "score_delta": 2.0},
-                        {"behavior_name": "cooperate", "score_delta": 1.0},
-                    ]
-                },
-            },
-            "alive": True,
-            "metadata": {},
-        }
-    ],
-    "resources": [
-        {
-            "id": "knowledge_pool",
-            "type": "knowledge",
-            "amount": 12,
-            "position": [5, 5],
-            "regeneration_rate": 0.2,
-            "max_amount": 20,
-            "metadata": {},
-        }
-    ],
-    "events": [],
-    "metrics": [
-        {"name": "diversity", "params": {"collection": "agents", "group_by_path": "type"}},
-        {"name": "entropy", "params": {"collection": "agents", "value_path": "type"}},
-        {"name": "interestingness", "params": {"collection": "agents", "group_by_path": "type"}},
-    ],
-    "metadata": {"generated_by": "worldsmithai_example"},
-}
+)
 
+_CORE_EVENT_ALIASES: Mapping[str, tuple[str, ...]] = MappingProxyType(
+    {
+        "id": ("event_id",),
+        "name": ("type", "event_type"),
+        "trigger_step": ("step", "at_step"),
+        "payload": ("data",),
+    }
+)
 
-class GenerationMode(str, Enum):
-    """Supported generation modes."""
+_CORE_WORLD_ALIASES: Mapping[str, tuple[str, ...]] = MappingProxyType({})
+_CORE_SCHEDULER_ALIASES: Mapping[str, tuple[str, ...]] = MappingProxyType({})
 
-    MODEL = "Qwen/Qwen2.5-3B"
-    FALLBACK = "fallback"
-    AUTO = "auto"
 
+class WorldFactoryError(RuntimeError):
+    """Base exception raised by the runtime world factory."""
 
-class ResponseFormat(str, Enum):
-    """Expected model response format."""
 
-    JSON_OBJECT = "json_object"
-    TEXT_WITH_JSON = "text_with_json"
+class RegistryResolutionError(WorldFactoryError):
+    """Raised when a behavior, policy, or runtime class cannot be resolved."""
 
 
-class WorldGenerationError(RuntimeError):
-    """Raised when natural-language-to-DSL generation fails."""
+class ConstructorBindingError(WorldFactoryError):
+    """Raised when DSL parameters cannot be bound to a constructor."""
 
 
-class ModelClientError(WorldGenerationError):
-    """Raised when an SLM client cannot be called successfully."""
+class RuntimeObjectBuildError(WorldFactoryError):
+    """Raised when a runtime object cannot be built."""
 
 
-class WorldGenerationValidationError(WorldGenerationError):
-    """Raised when generated DSL fails strict validation."""
+class WorldFactoryValidationError(WorldFactoryError):
+    """Raised when semantic DSL validation fails before world construction."""
 
     def __init__(self, report: ValidationReport) -> None:
-        """Initialize the exception with a semantic validation report."""
+        """Initialize the error from a validation report."""
 
         self.report = report
         super().__init__(report.summary())
 
 
-@runtime_checkable
-class SupportsGenerate(Protocol):
-    """Protocol for simple text generation clients."""
-
-    def generate(self, *args: Any, **kwargs: Any) -> Any:
-        """Generate text from prompt-like arguments."""
-
-
 @dataclass(frozen=True)
-class PromptBundle:
-    """Prompt payload sent to an SLM client.
+class RegistryLoadReport:
+    """Report describing dynamically loaded registry entries."""
 
-    The bundle includes both chat-style messages and flattened prompt text so
-    many different client APIs can be supported from root-level ``app.py``.
-    """
-
-    system_prompt: str
-    user_prompt: str
-    messages: tuple[Mapping[str, str], ...]
-    metadata: Mapping[str, Any] = field(default_factory=dict)
+    registry: Mapping[str, Any]
+    import_errors: Mapping[str, str] = field(default_factory=dict)
 
     @property
-    def text(self) -> str:
-        """Return a flattened prompt for completion-style models."""
+    def names(self) -> tuple[str, ...]:
+        """Return sorted registry names."""
 
-        return f"{self.system_prompt}\n\nUSER REQUEST:\n{self.user_prompt}"
+        return tuple(sorted(str(name) for name in self.registry.keys()))
 
     def to_dict(self) -> dict[str, Any]:
-        """Return a JSON-friendly prompt bundle."""
+        """Return a JSON-friendly registry load report."""
 
         return {
-            "system_prompt": self.system_prompt,
-            "user_prompt": self.user_prompt,
-            "messages": [dict(message) for message in self.messages],
-            "metadata": dict(self.metadata),
+            "names": list(self.names),
+            "count": len(self.registry),
+            "import_errors": copy.deepcopy(dict(self.import_errors)),
         }
 
 
 @dataclass(frozen=True)
-class WorldGenerationResult:
-    """Result returned by ``WorldGenerator.generate``.
-
-    Attributes:
-        spec: Validated world specification.
-        raw_response: Raw text returned by the model, or fallback JSON text.
-        parse_result: Parser result when available.
-        validation_report: Optional semantic validation report.
-        mode: Whether model or deterministic fallback produced the final spec.
-        prompt_bundle: Prompt used for model generation when available.
-        metadata: Additional diagnostics useful for Gradio display.
-    """
-
-    spec: WorldSpec
-    raw_response: str
-    parse_result: ParseResult | None = None
+class WorldBuildReport:
+    """Structured report generated during world construction."""
+
+    world_id: str
+    agent_ids: tuple[str, ...]
+    resource_ids: tuple[str, ...]
+    event_keys: tuple[str, ...]
+    behavior_registry_count: int
+    policy_registry_count: int
+    import_errors: Mapping[str, str] = field(default_factory=dict)
     validation_report: ValidationReport | None = None
-    mode: GenerationMode = GenerationMode.MODEL
-    prompt_bundle: PromptBundle | None = None
     metadata: Mapping[str, Any] = field(default_factory=dict)
 
     @property
-    def json_text(self) -> str:
-        """Return the generated world spec as formatted JSON."""
-
-        return self.spec.to_json_string(indent=2, exclude_none=True)
-
-    @property
-    def is_semantically_valid(self) -> bool:
-        """Return whether semantic validation passed or was not run."""
+    def valid(self) -> bool:
+        """Return whether the optional validation report is valid."""
 
         return self.validation_report is None or self.validation_report.is_valid
 
     def to_dict(self) -> dict[str, Any]:
-        """Return a JSON-friendly result summary."""
+        """Return a JSON-friendly build report."""
 
         return {
-            "world_id": self.spec.id,
-            "world_name": self.spec.name,
-            "mode": self.mode.value,
-            "agent_count": len(self.spec.agents),
-            "resource_count": len(self.spec.resources),
-            "event_count": len(self.spec.events),
-            "behavior_count": len(self.spec.behavior_names),
-            "is_semantically_valid": self.is_semantically_valid,
+            "world_id": self.world_id,
+            "agent_ids": list(self.agent_ids),
+            "resource_ids": list(self.resource_ids),
+            "event_keys": list(self.event_keys),
+            "agent_count": len(self.agent_ids),
+            "resource_count": len(self.resource_ids),
+            "event_count": len(self.event_keys),
+            "behavior_registry_count": self.behavior_registry_count,
+            "policy_registry_count": self.policy_registry_count,
+            "import_errors": copy.deepcopy(dict(self.import_errors)),
             "validation_report": None
             if self.validation_report is None
             else self.validation_report.to_dict(),
-            "parse_result": None if self.parse_result is None else self.parse_result.to_dict(),
             "metadata": copy.deepcopy(dict(self.metadata)),
         }
 
 
+@dataclass(frozen=True)
+class WorldBuildResult:
+    """Factory result containing the runtime world and build report."""
+
+    world: World
+    report: WorldBuildReport
+
+
 @dataclass
-class WorldGenerationConfig:
-    """Configuration for ``WorldGenerator``.
-
-    Defaults are designed for a Gradio demo:
-        - model output is parsed strictly,
-        - semantic validation runs but does not raise by default,
-        - deterministic fallback is enabled,
-        - generated worlds stay small enough for interactive simulation.
+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.
     """
 
-    mode: GenerationMode | str = GenerationMode.AUTO
-    response_format: ResponseFormat | str = ResponseFormat.JSON_OBJECT
+    validate_before_build: bool = True
 
-    system_prompt: str = DEFAULT_SYSTEM_PROMPT
-    include_format_guide: bool = True
-    include_example: bool = True
-    include_json_schema_excerpt: bool = False
+    strict_unknown_behaviors: bool = True
+    strict_unknown_policies: bool = True
+    strict_constructor_params: bool = True
 
-    default_steps: int = 60
-    default_seed: int = 0
-    max_agents_hint: int = 8
-    max_resources_hint: int = 6
+    include_disabled_behaviors: bool = False
+    include_disabled_events: bool = False
 
-    parser: WorldDSLParser = field(default_factory=WorldDSLParser)
+    attach_default_policy: bool = True
+    default_policy_type: str = "rule_policy"
 
-    semantic_validation: bool = True
-    strict_semantic_validation: bool = False
-    semantic_validation_config: ValidationConfig | None = None
+    attach_scheduler: bool = True
+    attach_dsl_spec_to_world: bool = True
 
-    fallback_on_model_error: bool = True
-    fallback_on_parse_error: bool = True
-    fallback_on_semantic_error: bool = False
+    behavior_modules: tuple[str, ...] = DEFAULT_BEHAVIOR_MODULES
+    policy_modules: tuple[str, ...] = DEFAULT_POLICY_MODULES
 
-    repair_attempts: int = 1
-    model_kwargs: Mapping[str, Any] = field(default_factory=dict)
+    behavior_registry: Mapping[str, Any] | None = None
+    policy_registry: Mapping[str, Any] | None = None
 
-    metadata: Mapping[str, Any] = field(default_factory=dict)
+    agent_class: type[Agent] = Agent
+    resource_class: type[Resource] = Resource
+    event_class: type[Event] = Event
+    world_class: type[World] = World
+    scheduler_class: type[Scheduler] | None = Scheduler
+
+    world_uses_mapping_collections: bool = True
+
+
+@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.
+    """
 
-    def resolved_mode(self) -> GenerationMode:
-        """Return normalized generation mode."""
+    name: str
+    trigger_step: int
+    payload: Mapping[str, Any] = field(default_factory=dict)
+    id: str | None = None
+    enabled: bool = True
+    repeat_interval: int | None = None
+    target_agent_ids: tuple[str, ...] = ()
+    target_resource_ids: tuple[str, ...] = ()
+    metadata: Mapping[str, Any] = field(default_factory=dict)
 
-        if isinstance(self.mode, GenerationMode):
-            return self.mode
-        return GenerationMode(str(self.mode))
+    def execute(self, world: World) -> dict[str, Any]:
+        """Execute the event in a domain-agnostic way.
 
-    def resolved_response_format(self) -> ResponseFormat:
-        """Return normalized response format."""
+        The fallback adapter does not mutate world state by default. It returns
+        a structured event outcome that schedulers, logs, metrics, or narrators
+        can consume.
+        """
 
-        if isinstance(self.response_format, ResponseFormat):
-            return self.response_format
-        return ResponseFormat(str(self.response_format))
+        return {
+            "event": self.name,
+            "event_id": self.id,
+            "trigger_step": self.trigger_step,
+            "enabled": self.enabled,
+            "payload": copy.deepcopy(dict(self.payload)),
+            "target_agent_ids": list(self.target_agent_ids),
+            "target_resource_ids": list(self.target_resource_ids),
+            "world_step": getattr(world, "step_count", None),
+        }
 
 
 @dataclass
-class DeterministicWorldSpecBuilder:
-    """Build a valid generic fallback ``WorldSpec`` without an SLM.
+class WorldFactory:
+    """Factory that converts ``WorldSpec`` into a runtime ``World``.
 
-    This fallback exists so the Gradio demo can still run when no SLM client is
-    configured or when the model returns invalid JSON. It does not replace the
-    SLM; it provides a safe baseline.
+    The factory owns behavior and policy registries. Registries may come from
+    default behavior/policy modules or from custom mappings supplied through
+    ``WorldFactoryConfig``.
     """
 
-    default_steps: int = 60
-    default_seed: int = 0
-    max_agents: int = 6
+    config: WorldFactoryConfig = field(default_factory=WorldFactoryConfig)
 
-    def build(
-        self,
-        prompt: str,
+    _behavior_registry: dict[str, Any] = field(default_factory=dict, init=False, repr=False)
+    _policy_registry: dict[str, Any] = field(default_factory=dict, init=False, repr=False)
+    _registry_import_errors: dict[str, str] = field(default_factory=dict, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        """Load configured behavior and policy registries."""
+
+        self._behavior_registry = self._build_behavior_registry()
+        self._policy_registry = self._build_policy_registry()
+
+    @property
+    def behavior_registry(self) -> Mapping[str, Any]:
+        """Return a read-only view of the behavior registry."""
+
+        return MappingProxyType(self._behavior_registry)
+
+    @property
+    def policy_registry(self) -> Mapping[str, Any]:
+        """Return a read-only view of the policy registry."""
+
+        return MappingProxyType(self._policy_registry)
+
+    @property
+    def registry_import_errors(self) -> Mapping[str, str]:
+        """Return registry import errors collected during initialization."""
+
+        return MappingProxyType(self._registry_import_errors)
+    
+    @staticmethod
+    def _behavior_runtime_id(
+        spec: BehaviorSpec,
         *,
-        constraints: Mapping[str, Any] | str | None = None,
-    ) -> WorldSpec:
-        """Build a deterministic world spec from prompt keywords."""
-
-        domain = self._infer_domain(prompt)
-        world_id = _slugify(f"{domain}_world")
-        roles = self._roles_for_domain(domain)[: max(1, int(self.max_agents))]
-        resources = self._resources_for_domain(domain)
-        goals = self._goals_for_domain(domain)
-
-        agents = tuple(
-            self._agent_spec(
-                index=index,
-                role=role,
-                domain=domain,
-                goals=goals,
-                total_agents=len(roles),
-            )
-            for index, role in enumerate(roles)
-        )
+        owner_agent_id: str | None,
+        behavior_index: int | None,
+    ) -> str:
+        """Return a deterministic runtime id for a behavior spec."""
 
-        resource_specs = tuple(
-            ResourceSpec(
-                id=f"{resource_type}_{index + 1}",
-                type=resource_type,
-                amount=float(10 + index * 4),
-                position=(float(2 + index * 2), float(7 - index % 4)),
-                regeneration_rate=0.1 if index == 0 else 0.0,
-                max_amount=float(30 + index * 5),
-                metadata={"domain": domain},
-            )
-            for index, resource_type in enumerate(resources)
-        )
+        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}"
+
+    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.
 
-        events = (
-            EventSpec(
-                id="midpoint_pressure",
-                name="midpoint_pressure",
-                trigger_step=max(1, self.default_steps // 2),
-                payload={
-                    "description": "A generic pressure event that can be narrated later.",
-                    "domain": domain,
-                },
-                enabled=True,
-                metadata={"generated_by": "fallback_builder"},
-            ),
+        Raises:
+            WorldFactoryValidationError: If semantic validation fails.
+            WorldFactoryError: If runtime construction fails.
+        """
+
+        return self.create_world_result(spec).world
+
+    def create_world_result(self, spec: WorldSpec | Mapping[str, Any]) -> WorldBuildResult:
+        """Create a world and return both runtime object and build report."""
+
+        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)
+        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)
 
-        description = self._description(prompt, domain, constraints)
-
-        return WorldSpec(
-            schema_version="1.0",
-            id=world_id,
-            name=_title_from_domain(domain),
-            description=description,
-            simulation=SimulationSpec(
-                steps=max(1, int(self.default_steps)),
-                seed=self.default_seed,
-                scheduler="sequential",
-                activation="sequential",
-                collect_history=True,
-            ),
-            space=SpaceSpec(
-                dimensions=2,
-                bounds=((0.0, 10.0), (0.0, 10.0)),
-                toroidal=False,
-                enforce_bounds=True,
-            ),
+        world = self._create_world_object(
+            spec=world_spec,
             agents=agents,
-            resources=resource_specs,
+            resources=resources,
             events=events,
-            metrics=(
-                {"name": "diversity", "params": {"collection": "agents", "group_by_path": "type"}},
-                {"name": "entropy", "params": {"collection": "agents", "value_path": "type"}},
-                {"name": "stability", "params": {"collection": "agents", "group_by_path": "type"}},
-                {"name": "interestingness", "params": {"collection": "agents", "group_by_path": "type"}},
-            ),
-            metadata={
-                "generated_by": "deterministic_fallback",
-                "domain": domain,
-                "source_prompt": prompt,
-            },
+            metrics=metrics,
         )
 
-    def _agent_spec(
-        self,
-        *,
-        index: int,
-        role: str,
-        domain: str,
-        goals: Sequence[str],
-        total_agents: int,
-    ) -> AgentSpec:
-        """Create one generic fallback agent spec."""
-
-        x = 1.0 + (index % 3) * 3.0
-        y = 1.0 + (index // 3) * 3.0
-        agent_id = f"{role}_{index + 1}"
-
-        target_agent_id = None
-        if total_agents > 1:
-            target_agent_id = f"{self._roles_for_domain(domain)[(index + 1) % total_agents]}_{((index + 1) % total_agents) + 1}"
-
-        goal_records = [
-            {
-                "id": goal,
-                "importance": float(len(goals) - goal_index),
-                "score": float(len(goals) - goal_index),
-                "description": f"{role} works toward {goal}",
-            }
-            for goal_index, goal in enumerate(goals)
-        ]
-
-        behaviors = [
-            BehaviorSpec(
-                    name="remember",
-                    params={
-                        "category": "initial_context",
-                        "content": {
-                            "role": role,
-                            "domain": domain,
-                            "note": "Seed memory created by fallback generator.",
-                        },
-                        "tags": ["initial", domain],
-                    },
-                ),
-            BehaviorSpec(name="evaluate", params={"category": "strategy"}),
-            BehaviorSpec(name="prioritize", params={"source_path": "memory.goals"}),
-            BehaviorSpec(name="choose_goal", params={}),
-            BehaviorSpec(
-                name="communicate",
-                params={
-                    "target_agent_id": target_agent_id,
-                    "message": f"{role}_status_update",
-                    "max_recipients": 1,
-                }
-                if target_agent_id is not None
-                else {"message": f"{role}_status_update", "max_recipients": 1},
-            ),
-            BehaviorSpec(
-                name="cooperate",
-                params={
-                    "target_agent_id": target_agent_id,
-                    "goal": goals[0],
-                    "effort": 1.0,
-                }
-                if target_agent_id is not None
-                else {"goal": goals[0], "effort": 1.0},
-            ),
-        ]
-
-        policy = PolicySpec(
-            type="rule_policy",
-            params={
-                "selection_strategy": "highest_score",
-                "rules": [
-                    {"behavior_name": "choose_goal", "score_delta": 4.0, "priority_delta": 1.0},
-                    {"behavior_name": "prioritize", "score_delta": 3.0},
-                    {"behavior_name": "communicate", "score_delta": 2.0},
-                    {"behavior_name": "cooperate", "score_delta": 1.5},
-                    {"behavior_name": "remember", "score_delta": 0.5},
-                    {"behavior_name": "evaluate", "score_delta": 0.25},
-                ],
-            },
-        )
+        if self.config.attach_scheduler:
+            self._attach_scheduler(world, world_spec)
 
-        return AgentSpec(
-            id=agent_id,
-            type=role,
-            position=(x, y),
-            state={
-                "energy": float(10 - index),
-                "credits": float(5 + index),
-                "influence": float(index + 1),
-                "domain_pressure": 0.2,
-            },
-            memory={
-                "goals": goal_records,
-                "known_options": {
-                    "cooperate": 1.0,
-                    "communicate": 0.8,
-                    "evaluate": 0.6,
-                },
-                "relationships": {},
-            },
-            goals=goal_records,
-            behaviors=tuple(behaviors),
-            policy=policy,
-            alive=True,
+        self._attach_world_metadata(world, world_spec)
+
+        report = WorldBuildReport(
+            world_id=world_spec.id,
+            agent_ids=tuple(agent.id for agent in world_spec.agents),
+            resource_ids=tuple(resource.id for resource in world_spec.resources),
+            event_keys=tuple(event.event_key for event in world_spec.events),
+            behavior_registry_count=len(self._behavior_registry),
+            policy_registry_count=len(self._policy_registry),
+            import_errors=copy.deepcopy(self._registry_import_errors),
+            validation_report=validation_report,
             metadata={
-                "domain": domain,
-                "generated_by": "deterministic_fallback",
+                "world_name": world_spec.name,
+                "schema_version": world_spec.schema_version,
+                "simulation_steps": world_spec.simulation.steps,
             },
         )
 
-    @staticmethod
-    def _infer_domain(prompt: str) -> str:
-        """Infer a broad fallback domain from prompt keywords."""
-
-        text = prompt.lower()
-
-        keyword_domains = (
-            ("farm", ("farm", "crop", "soil", "harvest", "animal", "pasture")),
-            ("medieval", ("medieval", "kingdom", "castle", "guild", "village", "empire")),
-            ("research", ("research", "scientist", "paper", "lab", "study", "knowledge")),
-            ("startup", ("startup", "founder", "investor", "customer", "market", "product")),
-            ("social", ("social", "network", "influencer", "community", "friend", "viral")),
-            ("transport", ("transport", "route", "traffic", "delivery", "ship", "vehicle")),
-            ("power", ("power", "grid", "energy", "battery", "generator", "electric")),
-            ("space", ("space", "colony", "planet", "terraform", "asteroid", "orbital")),
-            ("fantasy", ("fantasy", "dragon", "mana", "mage", "kingdom", "quest")),
+        logger.info(
+            "Created world %s with %s agent(s), %s resource(s), and %s event(s)",
+            world_spec.id,
+            len(agents),
+            len(resources),
+            len(events),
         )
 
-        for domain, keywords in keyword_domains:
-            if any(keyword in text for keyword in keywords):
-                return domain
+        return WorldBuildResult(world=world, report=report)
 
-        return "generic"
+    def create_agent(self, spec: AgentSpec) -> Agent:
+        """Create a runtime ``Agent`` from an ``AgentSpec``."""
 
-    @staticmethod
-    def _roles_for_domain(domain: str) -> tuple[str, ...]:
-        """Return fallback agent roles for a domain."""
-
-        roles_by_domain = {
-            "farm": ("farmer", "pollinator", "soil_guardian", "market_vendor"),
-            "medieval": ("ruler", "merchant", "artisan", "scholar", "guard"),
-            "research": ("scientist", "reviewer", "engineer", "curator", "funding_agent"),
-            "startup": ("founder", "customer", "investor", "operator", "competitor"),
-            "social": ("creator", "moderator", "member", "recommender", "critic"),
-            "transport": ("hub", "carrier", "dispatcher", "charger", "passenger"),
-            "power": ("generator", "storage_node", "consumer", "regulator", "maintainer"),
-            "space": ("colonist", "engineer", "botanist", "navigator", "miner"),
-            "fantasy": ("mage", "merchant", "guardian", "dragon", "healer"),
-            "generic": ("explorer", "builder", "trader", "learner", "coordinator"),
+        behaviors = tuple(
+            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
+        )
+        policy = self.create_policy_for_agent(spec)
+
+        params = {
+            "id": spec.id,
+            "type": spec.type,
+            "position": None if spec.position is None else tuple(spec.position),
+            "state": copy.deepcopy(spec.state),
+            "memory": copy.deepcopy(spec.memory),
+            "goals": copy.deepcopy(spec.goals),
+            "behaviors": behaviors,
+            "policy": policy,
+            "alive": bool(spec.alive),
         }
-        return roles_by_domain.get(domain, roles_by_domain["generic"])
 
-    @staticmethod
-    def _resources_for_domain(domain: str) -> tuple[str, ...]:
-        """Return fallback resource types for a domain."""
-
-        resources_by_domain = {
-            "farm": ("food", "water", "soil_health"),
-            "medieval": ("grain", "gold", "craft_materials"),
-            "research": ("knowledge", "funding", "attention"),
-            "startup": ("capital", "users", "compute"),
-            "social": ("attention", "trust", "content"),
-            "transport": ("capacity", "fuel", "demand"),
-            "power": ("energy", "storage", "load"),
-            "space": ("oxygen", "minerals", "habitat_capacity"),
-            "fantasy": ("mana", "relics", "influence"),
-            "generic": ("energy", "materials", "knowledge"),
-        }
-        return resources_by_domain.get(domain, resources_by_domain["generic"])
+        agent = self._instantiate_runtime_object(
+            self.config.agent_class,
+            params,
+            aliases=_CORE_AGENT_ALIASES,
+            strict=False,
+            path=f"agents.{spec.id}",
+            item_kind="agent",
+        )
 
-    @staticmethod
-    def _goals_for_domain(domain: str) -> tuple[str, ...]:
-        """Return fallback goal ids for a domain."""
-
-        goals_by_domain = {
-            "farm": ("sustain_harvest", "share_resources", "adapt_to_weather"),
-            "medieval": ("maintain_order", "grow_trade", "protect_settlement"),
-            "research": ("discover", "publish", "collaborate"),
-            "startup": ("find_users", "improve_product", "raise_capital"),
-            "social": ("grow_trust", "spread_useful_content", "moderate_conflict"),
-            "transport": ("deliver_reliably", "reduce_congestion", "balance_capacity"),
-            "power": ("meet_demand", "prevent_outage", "rebalance_energy"),
-            "space": ("survive_colony", "expand_habitat", "extract_resources"),
-            "fantasy": ("protect_realm", "gather_mana", "negotiate_alliances"),
-            "generic": ("survive", "learn", "cooperate"),
-        }
-        return goals_by_domain.get(domain, goals_by_domain["generic"])
+        self._safe_setattr(agent, "id", spec.id)
+        self._safe_setattr(agent, "type", spec.type)
+        self._safe_setattr(agent, "position", None if spec.position is None else tuple(spec.position))
+        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, "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)
+
+        return agent
+
+    def create_behavior(
+        self,
+        spec: BehaviorSpec,
+        *,
+        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.
+        """
 
-    @staticmethod
-    def _description(
-        prompt: str,
-        domain: str,
-        constraints: Mapping[str, Any] | str | None,
-    ) -> str:
-        """Build fallback world description."""
+        target = self._resolve_registry_item(
+            registry=self._behavior_registry,
+            name=spec.name,
+            strict=self.config.strict_unknown_behaviors,
+            item_kind="behavior",
+            path=f"behavior:{spec.name}",
+        )
 
-        constraint_text = ""
-        if constraints:
-            constraint_text = f" Constraints: {constraints}"
+        runtime_behavior_id = self._behavior_runtime_id(
+            spec,
+            owner_agent_id=owner_agent_id,
+            behavior_index=behavior_index,
+        )
 
-        return (
-            f"A deterministic fallback {domain} world generated from the prompt: "
-            f"{prompt.strip()[:240]}{constraint_text}"
+        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)
+
+        behavior = self._instantiate_runtime_object(
+            target,
+            params,
+            aliases={},
+            strict=self.config.strict_constructor_params,
+            path=f"behavior:{spec.name}.params",
+            item_kind="behavior",
         )
 
+        if not isinstance(behavior, Behavior) and not callable(getattr(behavior, "execute", None)):
+            raise RuntimeObjectBuildError(
+                f"Behavior {spec.name!r} did not produce an executable behavior object"
+            )
 
-@dataclass
-class WorldGenerator:
-    """Generate ``WorldSpec`` objects from natural language prompts.
+        self._safe_setattr(behavior, "id", runtime_behavior_id)
+        self._safe_setattr(behavior, "name", spec.name)
+        self._safe_setattr(behavior, "enabled", bool(spec.enabled))
+        self._safe_setattr(behavior, "priority", float(spec.priority))
+        self._safe_setattr(behavior, "tags", tuple(spec.tags))
+        self._safe_setattr(behavior, "metadata", copy.deepcopy(spec.metadata))
+        self._safe_setattr(behavior, "dsl_spec", spec)
 
-    The generator is intentionally adapter-neutral. A client can be any object
-    exposing ``generate``, ``complete``, ``chat``, or ``__call__``. The module
-    does not import a specific model SDK.
-    """
+        return behavior
 
-    client: Any | None = None
-    config: WorldGenerationConfig = field(default_factory=WorldGenerationConfig)
+    def create_policy_for_agent(self, agent_spec: AgentSpec) -> BasePolicy | None:
+        """Create the policy configured for an agent.
 
-    def generate(
-        self,
-        prompt: str,
-        *,
-        constraints: Mapping[str, Any] | str | None = None,
-        examples: Sequence[WorldSpec | Mapping[str, Any] | str] | None = None,
-        model_kwargs: Mapping[str, Any] | None = None,
-    ) -> WorldGenerationResult:
-        """Generate a validated ``WorldSpec`` from natural language.
+        If the agent has behaviors but omits a policy, the factory may attach a
+        default policy depending on configuration.
+        """
 
-        Args:
-            prompt: Natural language world description.
-            constraints: Optional extra constraints from the UI.
-            examples: Optional few-shot examples as specs, mappings, or strings.
-            model_kwargs: Optional generation kwargs for the model client.
+        policy_spec = agent_spec.policy
 
-        Returns:
-            ``WorldGenerationResult``.
+        if policy_spec is None and self.config.attach_default_policy and agent_spec.behaviors:
+            policy_spec = PolicySpec(type=self.config.default_policy_type, params={})
 
-        Raises:
-            WorldGenerationError: If generation fails and fallback is disabled.
-        """
+        if policy_spec is None:
+            return None
 
-        normalized_prompt = _require_prompt(prompt)
-        mode = self.config.resolved_mode()
+        return self.create_policy(policy_spec)
 
-        if mode is GenerationMode.FALLBACK or self.client is None:
-            return self._fallback_result(
-                normalized_prompt,
-                constraints=constraints,
-                reason="fallback_mode" if mode is GenerationMode.FALLBACK else "client_not_configured",
+    def create_policy(self, spec: PolicySpec) -> BasePolicy:
+        """Create a runtime policy object from a ``PolicySpec``."""
+
+        target = self._resolve_registry_item(
+            registry=self._policy_registry,
+            name=spec.type,
+            strict=self.config.strict_unknown_policies,
+            item_kind="policy",
+            path=f"policy:{spec.type}",
+        )
+
+        params = copy.deepcopy(spec.params)
+        params.setdefault("enabled", bool(spec.enabled))
+        if spec.metadata:
+            params.setdefault("metadata", copy.deepcopy(spec.metadata))
+
+        policy = self._instantiate_runtime_object(
+            target,
+            params,
+            aliases={},
+            strict=self.config.strict_constructor_params,
+            path=f"policy:{spec.type}.params",
+            item_kind="policy",
+        )
+
+        if not isinstance(policy, BasePolicy) and not callable(getattr(policy, "choose_action", None)):
+            raise RuntimeObjectBuildError(
+                f"Policy {spec.type!r} did not produce a valid policy object"
             )
 
-        prompt_bundle = self.build_prompt(
-            normalized_prompt,
-            constraints=constraints,
-            examples=examples,
+        self._safe_setattr(policy, "enabled", bool(spec.enabled))
+        self._safe_setattr(policy, "metadata", copy.deepcopy(spec.metadata))
+        self._safe_setattr(policy, "dsl_spec", spec)
+
+        return policy
+
+    def create_resource(self, spec: ResourceSpec) -> 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)
+
+        params = {
+            "id": spec.id,
+            "type": spec.type,
+            "amount": float(spec.amount),
+            "position": None if spec.position is None else tuple(spec.position),
+            "metadata": metadata,
+            "regeneration_rate": float(spec.regeneration_rate),
+            "max_amount": spec.max_amount,
+        }
+
+        resource = self._instantiate_runtime_object(
+            self.config.resource_class,
+            params,
+            aliases=_CORE_RESOURCE_ALIASES,
+            strict=False,
+            path=f"resources.{spec.id}",
+            item_kind="resource",
         )
 
-        try:
-            raw_response = self._call_client(prompt_bundle, model_kwargs=model_kwargs)
-        except Exception as exc:
-            if self.config.fallback_on_model_error and mode is GenerationMode.AUTO:
-                logger.warning("Model client failed; using deterministic fallback: %s", exc)
-                return self._fallback_result(
-                    normalized_prompt,
-                    constraints=constraints,
-                    reason="model_client_error",
-                    error=exc,
-                    prompt_bundle=prompt_bundle,
-                )
-            raise ModelClientError(f"Model client failed: {exc}") from exc
+        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._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)
+
+        return resource
+
+    def create_event(self, spec: EventSpec) -> Event | GenericScheduledEvent:
+        """Create a runtime event object from an ``EventSpec``."""
+
+        params = {
+            "id": spec.id,
+            "name": spec.name,
+            "trigger_step": int(spec.trigger_step),
+            "payload": copy.deepcopy(spec.payload),
+            "enabled": bool(spec.enabled),
+            "repeat_interval": spec.repeat_interval,
+            "target_agent_ids": tuple(spec.target_agent_ids),
+            "target_resource_ids": tuple(spec.target_resource_ids),
+            "metadata": copy.deepcopy(spec.metadata),
+        }
 
-        parse_result: ParseResult | None = None
-        parse_error: BaseException | None = None
-        current_response = raw_response
+        event_class = self.config.event_class
+        use_fallback = inspect.isabstract(event_class)
 
-        for attempt in range(max(1, int(self.config.repair_attempts) + 1)):
+        if use_fallback:
+            event: Event | GenericScheduledEvent = GenericScheduledEvent(**params)
+        else:
             try:
-                parse_result = self.config.parser.parse_result(current_response)
-                break
-            except Exception as exc:
-                parse_error = exc
-                if attempt >= int(self.config.repair_attempts):
-                    break
-                current_response = self._repair_response(
-                    prompt_bundle=prompt_bundle,
-                    bad_response=current_response,
-                    error=exc,
-                    model_kwargs=model_kwargs,
+                event = self._instantiate_runtime_object(
+                    event_class,
+                    params,
+                    aliases=_CORE_EVENT_ALIASES,
+                    strict=False,
+                    path=f"events.{spec.event_key}",
+                    item_kind="event",
                 )
-
-        if parse_result is None:
-            if self.config.fallback_on_parse_error and mode is GenerationMode.AUTO:
-                logger.warning("Generated DSL could not be parsed; using fallback: %s", parse_error)
-                return self._fallback_result(
-                    normalized_prompt,
-                    constraints=constraints,
-                    reason="parse_error",
-                    error=parse_error,
-                    raw_response=raw_response,
-                    prompt_bundle=prompt_bundle,
+            except WorldFactoryError:
+                logger.debug(
+                    "Falling back to GenericScheduledEvent for event %s",
+                    spec.event_key,
+                    exc_info=True,
                 )
+                event = GenericScheduledEvent(**params)
+
+        self._safe_setattr(event, "id", spec.id)
+        self._safe_setattr(event, "name", spec.name)
+        self._safe_setattr(event, "trigger_step", int(spec.trigger_step))
+        self._safe_setattr(event, "payload", copy.deepcopy(spec.payload))
+        self._safe_setattr(event, "enabled", bool(spec.enabled))
+        self._safe_setattr(event, "repeat_interval", spec.repeat_interval)
+        self._safe_setattr(event, "target_agent_ids", tuple(spec.target_agent_ids))
+        self._safe_setattr(event, "target_resource_ids", tuple(spec.target_resource_ids))
+        self._safe_setattr(event, "metadata", copy.deepcopy(spec.metadata))
+        self._safe_setattr(event, "dsl_spec", spec)
+
+        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.
+        """
 
-            raise WorldGenerationError(f"Generated DSL could not be parsed: {parse_error}") from parse_error
-
-        validation_report = self._semantic_validation(parse_result.spec)
-
-        if validation_report is not None and not validation_report.is_valid:
-            if self.config.strict_semantic_validation:
-                if self.config.fallback_on_semantic_error and mode is GenerationMode.AUTO:
-                    return self._fallback_result(
-                        normalized_prompt,
-                        constraints=constraints,
-                        reason="semantic_validation_error",
-                        raw_response=raw_response,
-                        prompt_bundle=prompt_bundle,
-                    )
-                raise WorldGenerationValidationError(validation_report)
-
-        return WorldGenerationResult(
-            spec=parse_result.spec,
-            raw_response=raw_response,
-            parse_result=parse_result,
-            validation_report=validation_report,
-            mode=GenerationMode.MODEL,
-            prompt_bundle=prompt_bundle,
-            metadata={
-                **copy.deepcopy(dict(self.config.metadata)),
-                "repair_attempts_used": 0 if current_response == raw_response else 1,
-            },
-        )
+        return {
+            "name": spec.name,
+            "params": copy.deepcopy(spec.params),
+            "enabled": bool(spec.enabled),
+            "metadata": copy.deepcopy(spec.metadata),
+        }
 
-    def generate_spec(
-        self,
-        prompt: str,
-        *,
-        constraints: Mapping[str, Any] | str | None = None,
-        examples: Sequence[WorldSpec | Mapping[str, Any] | str] | None = None,
-        model_kwargs: Mapping[str, Any] | None = None,
-    ) -> WorldSpec:
-        """Generate and return only the ``WorldSpec``."""
-
-        return self.generate(
-            prompt,
-            constraints=constraints,
-            examples=examples,
-            model_kwargs=model_kwargs,
-        ).spec
-
-    def generate_json(
+    def _create_world_object(
         self,
-        prompt: str,
         *,
-        constraints: Mapping[str, Any] | str | None = None,
-        examples: Sequence[WorldSpec | Mapping[str, Any] | str] | None = None,
-        model_kwargs: Mapping[str, Any] | None = None,
-    ) -> str:
-        """Generate and return formatted WorldSpec JSON."""
+        spec: WorldSpec,
+        agents: Sequence[Agent],
+        resources: Sequence[Resource],
+        events: Sequence[Event | GenericScheduledEvent],
+        metrics: Sequence[Mapping[str, Any]],
+    ) -> 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}
+        else:
+            agent_collection = tuple(agents)
+            resource_collection = tuple(resources)
+
+        metric_collection = {
+            str(metric["name"]): copy.deepcopy(dict(metric))
+            for metric in metrics
+            if "name" in metric
+        }
 
-        return self.generate(
-            prompt,
-            constraints=constraints,
-            examples=examples,
-            model_kwargs=model_kwargs,
-        ).json_text
+        params = {
+            "agents": agent_collection,
+            "resources": resource_collection,
+            "events": tuple(events),
+            "metrics": metric_collection,
+            "step_count": 0,
+        }
 
-    def build_prompt(
+        try:
+            world = self._instantiate_runtime_object(
+                self.config.world_class,
+                params,
+                aliases=_CORE_WORLD_ALIASES,
+                strict=False,
+                path=f"world:{spec.id}",
+                item_kind="world",
+            )
+        except WorldFactoryError:
+            logger.debug("Falling back to no-argument World constructor", exc_info=True)
+            world = self.config.world_class()
+
+        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)
+
+        return world
+
+    def _install_agents(self, world: World, agents: Sequence[Agent]) -> None:
+        """Install agents into the world using adders when available."""
+
+        if self.config.world_uses_mapping_collections:
+            self._safe_setattr(world, "agents", {})
+        else:
+            self._safe_setattr(world, "agents", [])
+
+        add_agent = getattr(world, "add_agent", None)
+        if callable(add_agent):
+            for agent in agents:
+                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})
+        else:
+            self._safe_setattr(world, "agents", list(agents))
+
+    def _install_resources(self, world: World, resources: Sequence[Resource]) -> None:
+        """Install resources into the world using adders when available."""
+
+        if self.config.world_uses_mapping_collections:
+            self._safe_setattr(world, "resources", {})
+        else:
+            self._safe_setattr(world, "resources", [])
+
+        add_resource = getattr(world, "add_resource", None)
+        if callable(add_resource):
+            for resource in resources:
+                add_resource(resource)
+            return
+
+        if self.config.world_uses_mapping_collections:
+            self._safe_setattr(
+                world,
+                "resources",
+                {str(getattr(resource, "id")): resource for resource in resources},
+            )
+        else:
+            self._safe_setattr(world, "resources", list(resources))
+
+    def _install_events(
         self,
-        prompt: str,
-        *,
-        constraints: Mapping[str, Any] | str | None = None,
-        examples: Sequence[WorldSpec | Mapping[str, Any] | str] | None = None,
-    ) -> PromptBundle:
-        """Build the prompt bundle sent to the model client."""
+        world: World,
+        events: Sequence[Event | GenericScheduledEvent],
+    ) -> None:
+        """Install events into the world using adders when available."""
 
-        sections: list[str] = []
-        sections.append(f"World request:\n{prompt.strip()}")
+        self._safe_setattr(world, "events", [])
 
-        if constraints:
-            sections.append(f"Additional constraints:\n{_serialize_constraints(constraints)}")
+        add_event = getattr(world, "add_event", None)
+        if callable(add_event):
+            for event in events:
+                add_event(event)
+            return
 
-        sections.append(
-            "Return a compact but complete WorldSmithAI WorldSpec JSON object. "
-            "The JSON must be parseable by Python json.loads."
-        )
+        self._safe_setattr(world, "events", list(events))
 
-        if self.config.include_format_guide:
-            sections.append(f"WorldSpec format guide:\n{WORLD_DSL_FORMAT_GUIDE}")
+    def _attach_scheduler(self, world: World, spec: WorldSpec) -> None:
+        """Attach a scheduler to the world when a scheduler class is configured."""
 
-        if self.config.include_json_schema_excerpt:
-            sections.append(f"Schema excerpt:\n{world_spec_schema_excerpt()}")
+        scheduler_class = self.config.scheduler_class
+        if scheduler_class is None:
+            return
 
-        example_payloads = self._example_payloads(examples)
-        if self.config.include_example and example_payloads:
-            sections.append("Example valid WorldSpec JSON:\n" + example_payloads[0])
+        params = {
+            "world": world,
+            "activation": spec.simulation.activation,
+            "scheduler": spec.simulation.scheduler,
+            "seed": spec.simulation.seed,
+        }
 
-        sections.append(
-            "Final answer requirements:\n"
-            "- JSON object only.\n"
-            "- No markdown.\n"
-            "- No comments.\n"
-            "- No Python code.\n"
-            "- No prose before or after the JSON."
+        try:
+            scheduler = self._instantiate_runtime_object(
+                scheduler_class,
+                params,
+                aliases=_CORE_SCHEDULER_ALIASES,
+                strict=False,
+                path=f"world:{spec.id}.scheduler",
+                item_kind="scheduler",
+            )
+        except WorldFactoryError:
+            logger.debug("Falling back to no-argument Scheduler constructor", exc_info=True)
+            scheduler = scheduler_class()
+
+        self._safe_setattr(scheduler, "world", world)
+        self._safe_setattr(scheduler, "activation", spec.simulation.activation)
+        self._safe_setattr(scheduler, "scheduler", spec.simulation.scheduler)
+        self._safe_setattr(scheduler, "seed", spec.simulation.seed)
+        self._safe_setattr(world, "scheduler", scheduler)
+
+    def _attach_world_metadata(self, world: World, spec: WorldSpec) -> None:
+        """Attach DSL metadata and simulation configuration to the runtime world."""
+
+        self._safe_setattr(world, "id", spec.id)
+        self._safe_setattr(world, "name", spec.name)
+        self._safe_setattr(world, "description", spec.description)
+        self._safe_setattr(world, "metadata", copy.deepcopy(spec.metadata))
+        self._safe_setattr(world, "simulation", spec.simulation)
+        self._safe_setattr(world, "simulation_config", spec.simulation.to_dict())
+        self._safe_setattr(world, "space", spec.space)
+        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 self.config.attach_dsl_spec_to_world:
+            self._safe_setattr(world, "dsl_spec", spec)
+
+    def _validate_before_build(self, spec: WorldSpec) -> ValidationReport | None:
+        """Optionally run semantic validation before object construction."""
+
+        if not self.config.validate_before_build:
+            return None
+
+        validation_config = ValidationConfig(
+            behavior_registry=self._behavior_registry,
+            policy_registry=self._policy_registry,
+            require_known_behaviors=self.config.strict_unknown_behaviors,
+            require_known_policies=self.config.strict_unknown_policies,
+            validate_constructor_params=self.config.strict_constructor_params,
+            unknown_registry_item_severity=ValidationSeverity.ERROR
+            if self.config.strict_unknown_behaviors or self.config.strict_unknown_policies
+            else ValidationSeverity.WARNING,
+            constructor_param_severity=ValidationSeverity.ERROR
+            if self.config.strict_constructor_params
+            else ValidationSeverity.WARNING,
         )
+        report = validate_world_spec(spec, config=validation_config)
 
-        user_prompt = "\n\n".join(sections)
-        system_prompt = self.config.system_prompt
+        if not report.is_valid:
+            raise WorldFactoryValidationError(report)
 
-        return PromptBundle(
-            system_prompt=system_prompt,
-            user_prompt=user_prompt,
-            messages=(
-                {"role": "system", "content": system_prompt},
-                {"role": "user", "content": user_prompt},
-            ),
-            metadata={
-                "response_format": self.config.resolved_response_format().value,
-                "default_steps": self.config.default_steps,
-                "max_agents_hint": self.config.max_agents_hint,
-                "max_resources_hint": self.config.max_resources_hint,
-            },
+        return report
+
+    def _coerce_world_spec(self, spec: WorldSpec | Mapping[str, Any]) -> WorldSpec:
+        """Return a ``WorldSpec`` from a spec-like object."""
+
+        if isinstance(spec, WorldSpec):
+            return spec
+
+        if isinstance(spec, Mapping):
+            return WorldSpec.model_validate(dict(spec))
+
+        raise TypeError(f"Expected WorldSpec or mapping, got {spec.__class__.__name__}")
+
+    def _build_behavior_registry(self) -> dict[str, Any]:
+        """Build the behavior registry from defaults and custom entries."""
+
+        registry: dict[str, Any] = {}
+
+        module_report = self._load_module_registries(
+            self.config.behavior_modules,
+            BEHAVIOR_REGISTRY_ATTRIBUTES,
+            base_class=Behavior,
         )
+        registry.update(module_report.registry)
+        self._registry_import_errors.update(module_report.import_errors)
 
-    def _example_payloads(
-        self,
-        examples: Sequence[WorldSpec | Mapping[str, Any] | str] | None,
-    ) -> tuple[str, ...]:
-        """Return serialized few-shot examples."""
+        if self.config.behavior_registry is not None:
+            registry.update({str(key): value for key, value in self.config.behavior_registry.items()})
+
+        return self._with_class_aliases(registry)
 
-        if examples is None:
-            return (json.dumps(DEFAULT_MINIMAL_EXAMPLE, indent=2),)
+    def _build_policy_registry(self) -> dict[str, Any]:
+        """Build the policy registry from defaults and custom entries."""
 
-        payloads: list[str] = []
+        registry: dict[str, Any] = {}
+
+        module_report = self._load_module_registries(
+            self.config.policy_modules,
+            POLICY_REGISTRY_ATTRIBUTES,
+            base_class=BasePolicy,
+        )
+        registry.update(module_report.registry)
+        self._registry_import_errors.update(module_report.import_errors)
 
-        for example in examples:
-            if isinstance(example, WorldSpec):
-                payloads.append(example.to_json_string(indent=2, exclude_none=True))
-            elif isinstance(example, Mapping):
-                payloads.append(json.dumps(example, indent=2))
-            elif isinstance(example, str):
-                payloads.append(example.strip())
+        if self.config.policy_registry is not None:
+            registry.update({str(key): value for key, value in self.config.policy_registry.items()})
 
-        return tuple(payload for payload in payloads if payload)
+        return self._with_class_aliases(registry)
 
-    def _call_client(
+    def _load_module_registries(
         self,
-        prompt_bundle: PromptBundle,
+        module_names: Sequence[str],
+        registry_attributes: Sequence[str],
         *,
-        model_kwargs: Mapping[str, Any] | None = None,
-    ) -> str:
-        """Call the configured model client and normalize its response to text."""
+        base_class: type[Any],
+    ) -> RegistryLoadReport:
+        """Load registry mappings from modules and discover named subclasses."""
 
-        if self.client is None:
-            raise ModelClientError("No model client is configured")
+        registry: dict[str, Any] = {}
+        import_errors: dict[str, str] = {}
 
-        kwargs = {
-            **copy.deepcopy(dict(self.config.model_kwargs)),
-            **copy.deepcopy(dict(model_kwargs or {})),
-        }
+        for module_name in module_names:
+            try:
+                module = import_module(module_name)
+            except Exception as exc:  # pragma: no cover - defensive for user modules
+                import_errors[str(module_name)] = f"{exc.__class__.__name__}: {exc}"
+                continue
 
-        callable_obj, call_style = self._resolve_client_callable(self.client)
+            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()})
 
-        call_kwargs = {
-            "prompt": prompt_bundle.text,
-            "system_prompt": prompt_bundle.system_prompt,
-            "user_prompt": prompt_bundle.user_prompt,
-            "messages": [dict(message) for message in prompt_bundle.messages],
-            "response_format": {"type": "json_object"},
-            **kwargs,
-        }
+            registry.update(self._discover_named_subclasses(module, base_class=base_class))
 
-        if call_style == "chat":
-            call_kwargs.setdefault("prompt", prompt_bundle.user_prompt)
+        return RegistryLoadReport(registry=registry, import_errors=import_errors)
 
-        response = _call_with_supported_kwargs(callable_obj, call_kwargs)
-        return normalize_model_response(response)
+    @staticmethod
+    def _discover_named_subclasses(module: Any, *, base_class: type[Any]) -> dict[str, Any]:
+        """Discover subclasses with a string ``name`` attribute from a module."""
 
-    def _repair_response(
-        self,
-        *,
-        prompt_bundle: PromptBundle,
-        bad_response: str,
-        error: BaseException,
-        model_kwargs: Mapping[str, Any] | None,
-    ) -> str:
-        """Ask the model client to repair malformed JSON."""
-
-        repair_user_prompt = (
-            "The previous response was not valid WorldSmithAI JSON.\n\n"
-            f"Parser error:\n{error}\n\n"
-            "Previous response:\n"
-            f"{bad_response[:8000]}\n\n"
-            "Return only a corrected WorldSpec JSON object. No markdown. No prose."
-        )
-        repair_bundle = PromptBundle(
-            system_prompt=prompt_bundle.system_prompt,
-            user_prompt=repair_user_prompt,
-            messages=(
-                {"role": "system", "content": prompt_bundle.system_prompt},
-                {"role": "user", "content": repair_user_prompt},
-            ),
-            metadata={"repair": True},
-        )
-        return self._call_client(repair_bundle, model_kwargs=model_kwargs)
+        discovered: dict[str, Any] = {}
+
+        for attribute_value in vars(module).values():
+            if not inspect.isclass(attribute_value):
+                continue
+
+            if attribute_value is base_class:
+                continue
+
+            try:
+                is_subclass = issubclass(attribute_value, base_class)
+            except TypeError:
+                is_subclass = False
+
+            if not is_subclass:
+                continue
+
+            name = getattr(attribute_value, "name", None)
+            if isinstance(name, str) and name:
+                discovered.setdefault(name, attribute_value)
+
+        return discovered
 
     @staticmethod
-    def _resolve_client_callable(client: Any) -> tuple[Callable[..., Any], str]:
-        """Resolve a callable generation method from a model client."""
-
-        for method_name, style in (
-            ("generate", "generate"),
-            ("complete", "complete"),
-            ("chat", "chat"),
-        ):
-            method = getattr(client, method_name, None)
-            if callable(method):
-                return method, style
-
-        if callable(client):
-            return client, "callable"
-
-        raise ModelClientError(
-            "Model client must expose generate, complete, chat, or be callable"
-        )
+    def _with_class_aliases(registry: Mapping[str, Any]) -> dict[str, Any]:
+        """Add class-name and ``name`` aliases to registry entries."""
 
-    def _semantic_validation(self, spec: WorldSpec) -> ValidationReport | None:
-        """Run optional semantic validation."""
+        expanded = {str(key): value for key, value in registry.items()}
 
-        if not self.config.semantic_validation:
-            return None
+        for key, value in list(expanded.items()):
+            class_name = getattr(value, "__name__", None)
+            if class_name:
+                expanded.setdefault(str(class_name), value)
 
-        validation_config = self.config.semantic_validation_config
-        if validation_config is None:
-            validation_config = ValidationConfig(
-                require_known_behaviors=True,
-                require_known_policies=True,
-                unknown_registry_item_severity=ValidationSeverity.WARNING,
-                constructor_param_severity=ValidationSeverity.WARNING,
-                unresolved_reference_severity=ValidationSeverity.WARNING,
-            )
+            runtime_name = getattr(value, "name", None)
+            if isinstance(runtime_name, str) and runtime_name:
+                expanded.setdefault(runtime_name, value)
+
+            expanded.setdefault(str(key).lower(), value)
 
-        return validate_world_spec(spec, config=validation_config)
+        return expanded
 
-    def _fallback_result(
+    def _resolve_registry_item(
         self,
-        prompt: str,
         *,
-        constraints: Mapping[str, Any] | str | None,
-        reason: str,
-        error: BaseException | None = None,
-        raw_response: str | None = None,
-        prompt_bundle: PromptBundle | None = None,
-    ) -> WorldGenerationResult:
-        """Build a deterministic fallback result."""
-
-        builder = DeterministicWorldSpecBuilder(
-            default_steps=self.config.default_steps,
-            default_seed=self.config.default_seed,
-            max_agents=min(max(1, int(self.config.max_agents_hint)), 6),
+        registry: Mapping[str, Any],
+        name: str,
+        strict: bool,
+        item_kind: str,
+        path: str,
+    ) -> Any:
+        """Resolve a registry item by exact or case-insensitive name."""
+
+        if name in registry:
+            return registry[name]
+
+        lower_name = name.lower()
+        if lower_name in registry:
+            return registry[lower_name]
+
+        for registered_name, item in registry.items():
+            if registered_name.lower() == lower_name:
+                return item
+
+        message = (
+            f"Unknown {item_kind} {name!r} at {path}. "
+            f"Known {item_kind}s: {sorted(str(key) for key in registry.keys())}"
         )
-        spec = builder.build(prompt, constraints=constraints)
-        validation_report = self._semantic_validation(spec)
-        raw = raw_response or spec.to_json_string(indent=2, exclude_none=True)
-
-        return WorldGenerationResult(
-            spec=spec,
-            raw_response=raw,
-            parse_result=None,
-            validation_report=validation_report,
-            mode=GenerationMode.FALLBACK,
-            prompt_bundle=prompt_bundle,
-            metadata={
-                **copy.deepcopy(dict(self.config.metadata)),
-                "fallback_reason": reason,
-                "error": None if error is None else f"{error.__class__.__name__}: {error}",
-            },
+
+        if strict:
+            raise RegistryResolutionError(message)
+
+        logger.warning(message)
+        return self._noop_behavior_factory(name) if item_kind == "behavior" else self._noop_policy_factory(name)
+
+    def _instantiate_runtime_object(
+        self,
+        target: Any,
+        params: Mapping[str, Any],
+        *,
+        aliases: Mapping[str, Sequence[str]],
+        strict: bool,
+        path: str,
+        item_kind: str,
+    ) -> Any:
+        """Instantiate a runtime object using signature-aware keyword binding."""
+
+        if not callable(target):
+            try:
+                return copy.deepcopy(target)
+            except Exception as exc:
+                raise RuntimeObjectBuildError(
+                    f"Registered {item_kind} at {path} is not callable and could not be copied"
+                ) from exc
+
+        kwargs = self._bind_constructor_kwargs(
+            target,
+            params,
+            aliases=aliases,
+            strict=strict,
+            path=path,
+            item_kind=item_kind,
         )
 
+        try:
+            return target(**kwargs)
+        except TypeError as exc:
+            raise ConstructorBindingError(
+                f"Could not instantiate {item_kind} at {path}: {exc}"
+            ) from exc
+        except Exception as exc:
+            raise RuntimeObjectBuildError(
+                f"Constructor for {item_kind} at {path} failed: {exc}"
+            ) from exc
 
-def generate_world_spec(
-    prompt: str,
-    *,
-    client: Any | None = None,
-    constraints: Mapping[str, Any] | str | None = None,
-    config: WorldGenerationConfig | None = None,
-    examples: Sequence[WorldSpec | Mapping[str, Any] | str] | None = None,
-    model_kwargs: Mapping[str, Any] | None = None,
-) -> WorldSpec:
-    """Convenience function that returns a generated ``WorldSpec``.
-
-    This is the simplest function to call from root-level ``app.py``.
-    """
+    def _bind_constructor_kwargs(
+        self,
+        target: Any,
+        params: Mapping[str, Any],
+        *,
+        aliases: Mapping[str, Sequence[str]],
+        strict: bool,
+        path: str,
+        item_kind: str,
+    ) -> dict[str, Any]:
+        """Filter and alias params according to a target constructor signature."""
 
-    generator = WorldGenerator(client=client, config=config or WorldGenerationConfig())
-    return generator.generate_spec(
-        prompt,
-        constraints=constraints,
-        examples=examples,
-        model_kwargs=model_kwargs,
-    )
+        working = copy.deepcopy(dict(params))
+        signature_info = self._constructor_signature_info(target)
 
+        if signature_info is None:
+            return working
 
-def generate_world_json(
-    prompt: str,
-    *,
-    client: Any | None = None,
-    constraints: Mapping[str, Any] | str | None = None,
-    config: WorldGenerationConfig | None = None,
-    examples: Sequence[WorldSpec | Mapping[str, Any] | str] | None = None,
-    model_kwargs: Mapping[str, Any] | None = None,
-) -> str:
-    """Convenience function that returns generated WorldSpec JSON."""
-
-    generator = WorldGenerator(client=client, config=config or WorldGenerationConfig())
-    return generator.generate_json(
-        prompt,
-        constraints=constraints,
-        examples=examples,
-        model_kwargs=model_kwargs,
-    )
-
-
-def generate_world_result(
-    prompt: str,
-    *,
-    client: Any | None = None,
-    constraints: Mapping[str, Any] | str | None = None,
-    config: WorldGenerationConfig | None = None,
-    examples: Sequence[WorldSpec | Mapping[str, Any] | str] | None = None,
-    model_kwargs: Mapping[str, Any] | None = None,
-) -> WorldGenerationResult:
-    """Convenience function that returns the full generation result."""
-
-    generator = WorldGenerator(client=client, config=config or WorldGenerationConfig())
-    return generator.generate(
-        prompt,
-        constraints=constraints,
-        examples=examples,
-        model_kwargs=model_kwargs,
-    )
-
-
-def build_world_generation_prompt(
-    prompt: str,
-    *,
-    constraints: Mapping[str, Any] | str | None = None,
-    config: WorldGenerationConfig | None = None,
-) -> PromptBundle:
-    """Build the prompt bundle without calling a model."""
+        allowed_params, required_params, accepts_var_keyword = signature_info
 
-    generator = WorldGenerator(client=None, config=config or WorldGenerationConfig())
-    return generator.build_prompt(prompt, constraints=constraints)
+        if accepts_var_keyword:
+            return working
 
+        for canonical_name, alias_names in aliases.items():
+            if canonical_name not in working:
+                continue
 
-def normalize_model_response(response: Any) -> str:
-    """Normalize common model-client response shapes into text.
+            if canonical_name in allowed_params:
+                continue
 
-    Supported shapes:
-        - plain string
-        - bytes
-        - mapping with text/content/generated_text/output
-        - OpenAI-like mapping with choices[0].message.content
-        - object with text/content/generated_text attributes
-    """
+            for alias_name in alias_names:
+                if alias_name in allowed_params and alias_name not in working:
+                    working[alias_name] = working[canonical_name]
+                    break
 
-    if response is None:
-        raise ModelClientError("Model client returned None")
+        unknown_params = set(working.keys()) - allowed_params
+        if unknown_params and strict:
+            raise ConstructorBindingError(
+                f"Unknown constructor parameter(s) for {item_kind} at {path}: "
+                f"{sorted(unknown_params)}. Allowed parameters: {sorted(allowed_params)}"
+            )
 
-    if isinstance(response, str):
-        return response.strip()
+        filtered = {
+            key: value
+            for key, value in working.items()
+            if key in allowed_params
+        }
 
-    if isinstance(response, bytes):
-        return response.decode("utf-8").strip()
+        missing_required = required_params - set(filtered.keys())
+        if missing_required:
+            raise ConstructorBindingError(
+                f"Missing required constructor parameter(s) for {item_kind} at {path}: "
+                f"{sorted(missing_required)}"
+            )
 
-    if isinstance(response, Mapping):
-        direct = _first_present(
-            response,
-            ("text", "content", "generated_text", "output", "response"),
-        )
-        if direct is not None:
-            return normalize_model_response(direct)
-
-        choices = response.get("choices")
-        if isinstance(choices, Sequence) and choices:
-            first_choice = choices[0]
-            if isinstance(first_choice, Mapping):
-                message = first_choice.get("message")
-                if isinstance(message, Mapping) and message.get("content") is not None:
-                    return normalize_model_response(message["content"])
-                if first_choice.get("text") is not None:
-                    return normalize_model_response(first_choice["text"])
-
-        if response.get("data") is not None:
-            return normalize_model_response(response["data"])
-
-    for attribute in ("text", "content", "generated_text", "output", "response"):
-        value = getattr(response, attribute, None)
-        if value is not None:
-            return normalize_model_response(value)
-
-    raise ModelClientError(
-        f"Could not extract text from model response of type {response.__class__.__name__}"
-    )
-
-
-def world_spec_schema_excerpt() -> str:
-    """Return a compact schema guide suitable for small-model prompts."""
-
-    excerpt = {
-        "WorldSpec": {
-            "required": ["id", "name", "agents", "resources", "events"],
-            "fields": {
-                "schema_version": "string",
-                "id": "string",
-                "name": "string",
-                "description": "string|null",
-                "simulation": "SimulationSpec",
-                "space": "SpaceSpec|null",
-                "agents": "AgentSpec[]",
-                "resources": "ResourceSpec[]",
-                "events": "EventSpec[]",
-                "metrics": "MetricSpec[]",
-                "metadata": "object",
-            },
-        },
-        "AgentSpec": {
-            "fields": {
-                "id": "string",
-                "type": "string",
-                "position": "number[]|null",
-                "state": "object",
-                "memory": "object",
-                "goals": "JSON",
-                "behaviors": "BehaviorSpec[]",
-                "policy": "PolicySpec|null",
-                "alive": "boolean",
-                "metadata": "object",
-            }
-        },
-        "BehaviorSpec": {"fields": {"name": "string", "params": "object"}},
-        "PolicySpec": {"fields": {"type": "string", "params": "object"}},
-        "ResourceSpec": {
-            "fields": {
-                "id": "string",
-                "type": "string",
-                "amount": "number",
-                "position": "number[]|null",
-                "regeneration_rate": "number",
-                "max_amount": "number|null",
-                "metadata": "object",
-            }
-        },
-        "EventSpec": {
-            "fields": {
-                "id": "string|null",
-                "name": "string",
-                "trigger_step": "integer",
-                "payload": "object",
-                "enabled": "boolean",
-            }
-        },
-    }
-    return json.dumps(excerpt, indent=2)
+        return filtered
 
+    @staticmethod
+    def _constructor_signature_info(target: Any) -> tuple[set[str], set[str], bool] | None:
+        """Return constructor binding information for a callable target."""
 
-def extract_json_object_text(text: str) -> str:
-    """Extract the first balanced JSON object from text.
+        try:
+            signature = inspect.signature(target)
+        except (TypeError, ValueError):
+            return None
 
-    This is exposed as a utility for app-level debugging. The parser already
-    uses equivalent extraction internally.
-    """
+        allowed_params: set[str] = set()
+        required_params: set[str] = set()
+        accepts_var_keyword = False
 
-    parser = WorldDSLParser()
-    return parser.extract_json_text(text)
+        for name, parameter in signature.parameters.items():
+            if name == "self":
+                continue
 
+            if parameter.kind is inspect.Parameter.VAR_KEYWORD:
+                accepts_var_keyword = True
+                continue
 
-def _call_with_supported_kwargs(callable_obj: Callable[..., Any], kwargs: Mapping[str, Any]) -> Any:
-    """Call a function using only kwargs supported by its signature.
+            if parameter.kind is inspect.Parameter.VAR_POSITIONAL:
+                continue
 
-    If the callable accepts ``**kwargs``, all supplied kwargs are passed.
-    Otherwise unsupported kwargs are filtered out. If no matching keyword is
-    accepted but a positional prompt appears possible, the flattened prompt is
-    passed positionally.
-    """
+            if parameter.kind not in {
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                inspect.Parameter.KEYWORD_ONLY,
+            }:
+                continue
 
-    try:
-        signature = inspect.signature(callable_obj)
-    except (TypeError, ValueError):
-        return callable_obj(**dict(kwargs))
+            allowed_params.add(name)
 
-    parameters = signature.parameters
-    accepts_var_keyword = any(
-        parameter.kind is inspect.Parameter.VAR_KEYWORD
-        for parameter in parameters.values()
-    )
+            if parameter.default is inspect.Parameter.empty:
+                required_params.add(name)
 
-    if accepts_var_keyword:
-        return callable_obj(**dict(kwargs))
+        return allowed_params, required_params, accepts_var_keyword
 
-    accepted = {
-        key: value
-        for key, value in kwargs.items()
-        if key in parameters
-    }
+    @staticmethod
+    def _safe_setattr(instance: Any, name: str, value: Any) -> bool:
+        """Set an attribute defensively.
 
-    if accepted:
-        return callable_obj(**accepted)
+        Returns:
+            ``True`` if the attribute was set, otherwise ``False``.
+        """
 
-    positional_params = [
-        parameter
-        for parameter in parameters.values()
-        if parameter.kind
-        in {
-            inspect.Parameter.POSITIONAL_ONLY,
-            inspect.Parameter.POSITIONAL_OR_KEYWORD,
-        }
-    ]
+        try:
+            setattr(instance, name, value)
+            return True
+        except Exception:
+            logger.debug(
+                "Could not set attribute %s on %s",
+                name,
+                instance.__class__.__name__,
+                exc_info=True,
+            )
+            return False
 
-    if positional_params and "prompt" in kwargs:
-        return callable_obj(kwargs["prompt"])
+    @staticmethod
+    def _noop_behavior_factory(name: str) -> type[Behavior]:
+        """Create a no-op behavior class for permissive unknown behavior mode."""
 
-    return callable_obj()
+        class NoOpBehavior(Behavior):
+            """Fallback behavior used only when unknown behaviors are permissive."""
 
+            behavior_name = name
 
-def _first_present(mapping: Mapping[str, Any], keys: Sequence[str]) -> Any:
-    """Return first present non-null mapping value."""
+            def check_preconditions(self, agent: Agent, world: World) -> bool:
+                """Return False so unknown behavior never executes."""
 
-    for key in keys:
-        if key in mapping and mapping[key] is not None:
-            return mapping[key]
-    return None
+                del agent, world
+                return False
 
+            def execute(self, agent: Agent, world: World) -> dict[str, Any]:
+                """Return a structured no-op result."""
 
-def _serialize_constraints(constraints: Mapping[str, Any] | str) -> str:
-    """Serialize UI constraints for prompt inclusion."""
+                del world
+                return {
+                    "behavior": self.behavior_name,
+                    "actor_id": getattr(agent, "id", None),
+                    "success": False,
+                    "details": {"reason": "unknown_behavior_noop"},
+                }
 
-    if isinstance(constraints, str):
-        return constraints.strip()
+        NoOpBehavior.name = name  # type: ignore[attr-defined]
+        return NoOpBehavior
 
-    return json.dumps(constraints, indent=2, sort_keys=True)
+    @staticmethod
+    def _noop_policy_factory(name: str) -> type[BasePolicy]:
+        """Create a no-op policy class for permissive unknown policy mode."""
 
+        class NoOpPolicy(BasePolicy):
+            """Fallback policy used only when unknown policies are permissive."""
 
-def _require_prompt(prompt: str) -> str:
-    """Validate and normalize a user prompt."""
+            policy_name_value = name
 
-    normalized = str(prompt).strip()
-    if not normalized:
-        raise WorldGenerationError("World generation prompt must not be empty")
-    return normalized
+            def choose_action(
+                self,
+                agent: Agent,
+                world: World,
+                behaviors: Sequence[Behavior] | Mapping[str, Behavior] | None = None,
+            ) -> Behavior | None:
+                """Choose no behavior."""
 
+                del agent, world, behaviors
+                return None
 
-def _slugify(value: str) -> str:
-    """Return a stable lowercase identifier."""
+        NoOpPolicy.name = name  # type: ignore[attr-defined]
+        return NoOpPolicy
 
-    lowered = value.lower().strip()
-    slug = re.sub(r"[^a-z0-9]+", "_", lowered)
-    slug = re.sub(r"_+", "_", slug).strip("_")
-    return slug or "world"
 
+def create_world(
+    spec: WorldSpec | Mapping[str, Any],
+    *,
+    config: WorldFactoryConfig | None = None,
+) -> World:
+    """Convenience function that creates a runtime world from a spec."""
 
-def _title_from_domain(domain: str) -> str:
-    """Return a human-readable fallback world title."""
+    return WorldFactory(config=config or WorldFactoryConfig()).create_world(spec)
+
+
+def create_world_result(
+    spec: WorldSpec | Mapping[str, Any],
+    *,
+    config: WorldFactoryConfig | None = None,
+) -> WorldBuildResult:
+    """Convenience function that creates a world and returns its build report."""
 
-    words = domain.replace("_", " ").split()
-    return " ".join(word.capitalize() for word in words) + " World"
+    return WorldFactory(config=config or WorldFactoryConfig()).create_world_result(spec)
 
 
 __all__ = [
-    "DEFAULT_MINIMAL_EXAMPLE",
-    "DEFAULT_SYSTEM_PROMPT",
-    "WORLD_DSL_FORMAT_GUIDE",
-    "DeterministicWorldSpecBuilder",
-    "GenerationMode",
-    "ModelClientError",
-    "PromptBundle",
-    "ResponseFormat",
-    "SupportsGenerate",
-    "WorldGenerationConfig",
-    "WorldGenerationError",
-    "WorldGenerationResult",
-    "WorldGenerationValidationError",
-    "WorldGenerator",
-    "build_world_generation_prompt",
-    "extract_json_object_text",
-    "generate_world_json",
-    "generate_world_result",
-    "generate_world_spec",
-    "normalize_model_response",
-    "world_spec_schema_excerpt",
+    "BEHAVIOR_REGISTRY_ATTRIBUTES",
+    "DEFAULT_BEHAVIOR_MODULES",
+    "DEFAULT_POLICY_MODULES",
+    "GenericScheduledEvent",
+    "ConstructorBindingError",
+    "POLICY_REGISTRY_ATTRIBUTES",
+    "RegistryLoadReport",
+    "RegistryResolutionError",
+    "RuntimeObjectBuildError",
+    "WorldBuildReport",
+    "WorldBuildResult",
+    "WorldFactory",
+    "WorldFactoryConfig",
+    "WorldFactoryError",
+    "WorldFactoryValidationError",
+    "create_world",
+    "create_world_result",
 ]