okstra 0.163.2 → 0.164.0

package/runtime/python/okstra_ctl/models.py

@@ -1,220 +1,33 @@
-"""Model catalog: display / execution / pricing / picker for okstra workers.
+"""Compatibility exports for the provider model catalog.
 
-Single reference point. Adding a model = one ModelSpec entry here. Changing a
-role default = one ROLE_DEFAULTS line here.
+Provider value objects live in ``domain`` and catalog entries are discovered
+from provider adapters. This module preserves the established public helpers.
 """
 from __future__ import annotations
 
-from dataclasses import dataclass
-from typing import Mapping, Optional
-
-
-@dataclass(frozen=True)
-class ModelSpec:
-    display: str
-    execution: str
-    pricing: Optional[tuple[float, float, float]] = None
-    in_picker: bool = False           # exposed in the wizard 3-option picker
-
-
-CLAUDE = {
-    "fable": ModelSpec("fable", "fable", in_picker=True),
-    "fable-5": ModelSpec("fable-5", "claude-fable-5"),
-    "claude-fable-5": ModelSpec("fable-5", "claude-fable-5"),
-    "opus": ModelSpec("opus", "opus", in_picker=True),
-    "opus-5": ModelSpec("opus-5", "claude-opus-5"),
-    "claude-opus-5": ModelSpec("opus-5", "claude-opus-5"),
-    "opus-4-8": ModelSpec("opus-4-8", "claude-opus-4-8"),
-    "claude-opus-4-8": ModelSpec("opus-4-8", "claude-opus-4-8"),
-    "opus-4-7": ModelSpec("opus-4-7", "claude-opus-4-7"),
-    "claude-opus-4-7": ModelSpec("opus-4-7", "claude-opus-4-7"),
-    "opus-4-6": ModelSpec("opus-4-6", "claude-opus-4-6"),
-    "claude-opus-4-6": ModelSpec("opus-4-6", "claude-opus-4-6"),
-    "sonnet": ModelSpec("sonnet", "sonnet", in_picker=True),
-    "sonnet-5": ModelSpec("sonnet-5", "claude-sonnet-5", in_picker=True),
-    "claude-sonnet-5": ModelSpec("sonnet-5", "claude-sonnet-5"),
-    "sonnet-4-6": ModelSpec("sonnet-4-6", "claude-sonnet-4-6"),
-    "claude-sonnet-4-6": ModelSpec("sonnet-4-6", "claude-sonnet-4-6"),
-    "haiku": ModelSpec("haiku", "haiku", in_picker=True),
-    "haiku-4-5": ModelSpec("haiku-4-5", "claude-haiku-4-5"),
-    "claude-haiku-4-5": ModelSpec("haiku-4-5", "claude-haiku-4-5"),
-    "claude-haiku-4-5-20251001": ModelSpec("haiku-4-5", "claude-haiku-4-5-20251001"),
-}
-# `agy` rejects a bare execution slug — it demands a tier, spelled as a suffix
-# on the slug itself ("gemini-3.1-pro-high"), and its list is host/version-
-# specific. model_discovery.normalize_execution_for_dispatch appends the role's
-# effort to ModelSpec.execution at dispatch time. `display` is okstra-facing
-# only and never reaches agy. agy also serves Claude/GPT-OSS models on some
-# installs; those carry their tier inline and take no suffix.
-ANTIGRAVITY = {
-    "gemini-3.1-pro": ModelSpec("Gemini 3.1 Pro", "gemini-3.1-pro", in_picker=True),
-    "gemini 3.1 pro": ModelSpec("Gemini 3.1 Pro", "gemini-3.1-pro"),
-    "gemini-3.6-flash": ModelSpec("Gemini 3.6 Flash", "gemini-3.6-flash", in_picker=True),
-    "gemini 3.6 flash": ModelSpec("Gemini 3.6 Flash", "gemini-3.6-flash"),
-    "gemini-3.5-flash": ModelSpec("Gemini 3.5 Flash", "gemini-3.5-flash", in_picker=True),
-    "gemini 3.5 flash": ModelSpec("Gemini 3.5 Flash", "gemini-3.5-flash"),
-}
-CODEX = {
-    # ChatGPT-account host (agy/codex) serves 5.6 without per-token billing → pricing=None.
-    "gpt-5.6-sol": ModelSpec("gpt-5.6-sol", "gpt-5.6-sol", None, in_picker=True),
-    "gpt-5.6": ModelSpec("gpt-5.6", "gpt-5.6", (5.00, 0.50, 30.0), in_picker=True),
-    "gpt-5.5": ModelSpec("gpt-5.5", "gpt-5.5", (5.00, 0.50, 30.0), in_picker=True),
-    "gpt-5.4": ModelSpec("gpt-5.4", "gpt-5.4", (2.50, 0.25, 15.0), in_picker=True),
-    "gpt-5.4-mini": ModelSpec("gpt-5.4-mini", "gpt-5.4-mini", (0.75, 0.075, 4.50), in_picker=True),
-    "gpt-5.3-codex": ModelSpec("gpt-5.4", "gpt-5.4"),
-    "gpt-5.2": ModelSpec("gpt-5.2", "gpt-5.2", (1.75, 0.175, 14.0)),
-    "codex-auto-review": ModelSpec("codex-auto-review", "codex-auto-review"),
-}
-GROK = {
-    "grok-build-0.1": ModelSpec(
-        "grok-build-0.1", "grok-build-0.1", (1.00, 0.20, 2.00), in_picker=True,
-    ),
-    "grok-4.5": ModelSpec(
-        "grok-4.5", "grok-4.5", (2.00, 0.30, 6.00), in_picker=True,
-    ),
-}
-KIMI = {
-    "kimi-k2.7-code": ModelSpec(
-        "Kimi K2.7 Code", "kimi-k2.7-code", (0.95, 0.19, 4.00), in_picker=True,
-    ),
-    "kimi k2.7 code": ModelSpec("Kimi K2.7 Code", "kimi-k2.7-code"),
-    "kimi-for-coding": ModelSpec(
-        "Kimi K2.7 Code", "kimi-for-coding", in_picker=True,
-    ),
-    "kimi-k3": ModelSpec(
-        "Kimi K3", "kimi-k3", (3.00, 0.30, 15.00), in_picker=True,
-    ),
-    "kimi k3": ModelSpec("Kimi K3", "kimi-k3"),
-    "k3": ModelSpec("Kimi K3", "k3", in_picker=True),
-    "k3-256k": ModelSpec("Kimi K3 256K", "k3-256k", in_picker=True),
-    "kimi k3 256k": ModelSpec("Kimi K3 256K", "k3-256k"),
-}
-
+from typing import Optional
+
+from .domain.provider import (
+    LeadLaunchSpec,
+    ModelAssignment,
+    ModelSpec,
+    ProviderSpec,
+    UnknownModelError,
+    UnknownProviderError,
+)
+from .registry.provider_registry import default_provider_registry
+
+
+PROVIDERS = default_provider_registry().providers
+CLAUDE = PROVIDERS["claude"].models
+ANTIGRAVITY = PROVIDERS["antigravity"].models
+CODEX = PROVIDERS["codex"].models
+GROK = PROVIDERS["grok"].models
+KIMI = PROVIDERS["kimi"].models
+PROVIDER_MAPPINGS = {provider: spec.models for provider, spec in PROVIDERS.items()}
 ANALYSIS_ROLES = frozenset({"analyser", "critic"})
 IMPLEMENTATION_ROLES = frozenset({"executor", "verifier"})
 
-
-@dataclass(frozen=True)
-class LeadLaunchSpec:
-    """How to start this provider's CLI as an interactive lead session.
-
-    The worker wrappers cannot serve here: they run one non-interactive turn and
-    exit, while a lead owns the session the user talks to. Empty `prompt_flag`
-    means the CLI takes the prompt positionally; empty `session_id_flag` means it
-    has no resumable session id and resumes from artifacts instead.
-    """
-
-    executable: str
-    model_flag: str
-    prompt_flag: str = ""
-    session_id_flag: str = ""
-    # Flags that lift the CLI's own sandbox, and what the user is agreeing to by
-    # accepting them. Empty when the CLI does not sandbox itself by default.
-    sandbox_waiver: tuple[str, ...] = ()
-    sandbox_waiver_note: str = ""
-
-
-@dataclass(frozen=True)
-class ProviderSpec:
-    provider: str
-    display_label: str
-    models: Mapping[str, ModelSpec]
-    default_models: Mapping[str, str]
-    wrapper: str
-    supported_roles: frozenset[str]
-    lead_launch: Optional[LeadLaunchSpec] = None
-
-
-PROVIDERS = {
-    "claude": ProviderSpec(
-        provider="claude",
-        display_label="Claude",
-        models=CLAUDE,
-        default_models={
-            "lead": "opus",
-            "analyser": "opus",
-            "critic": "opus",
-            "executor": "opus",
-            "verifier": "opus",
-            "report-writer": "sonnet",
-        },
-        wrapper="okstra-claude-exec.sh",
-        supported_roles=frozenset(
-            {"lead", "analyser", "critic", "executor", "verifier", "report-writer"}
-        ),
-        lead_launch=LeadLaunchSpec(
-            executable="claude",
-            model_flag="--model",
-            session_id_flag="--session-id",
-        ),
-    ),
-    "antigravity": ProviderSpec(
-        provider="antigravity",
-        display_label="Antigravity",
-        models=ANTIGRAVITY,
-        default_models={role: "gemini-3.1-pro" for role in (
-            "lead", "analyser", "critic", "executor", "verifier",
-        )},
-        wrapper="okstra-antigravity-exec.sh",
-        supported_roles=frozenset(
-            {"lead", "analyser", "critic", "executor", "verifier"}
-        ),
-        lead_launch=LeadLaunchSpec(
-            executable="agy",
-            model_flag="--model",
-            # Without this the prompt runs once and the session ends; okstra
-            # needs the lead to stay and drive the remaining phases.
-            prompt_flag="--prompt-interactive",
-        ),
-    ),
-    "codex": ProviderSpec(
-        provider="codex",
-        display_label="Codex",
-        models=CODEX,
-        default_models={role: "gpt-5.6-sol" for role in (
-            "lead", "analyser", "critic", "executor", "verifier", "report-writer",
-        )},
-        wrapper="okstra-codex-exec.sh",
-        supported_roles=frozenset(
-            {"lead", "analyser", "critic", "executor", "verifier", "report-writer"}
-        ),
-        lead_launch=LeadLaunchSpec(
-            executable="codex",
-            model_flag="-m",
-            # A codex session sandboxes itself, and everything it spawns inherits
-            # that — okstra's dispatch and every worker CLI with it. Measured:
-            # the cmux socket returns EPERM and each worker dies unable to write
-            # its own config. A sandboxed lead cannot run okstra at all.
-            sandbox_waiver=("-s", "danger-full-access"),
-            sandbox_waiver_note=(
-                "codex will start without its filesystem and network sandbox, "
-                "which okstra needs so the lead can reach cmux and start worker "
-                "CLIs."
-            ),
-        ),
-    ),
-    "grok": ProviderSpec(
-        provider="grok",
-        display_label="Grok",
-        models=GROK,
-        default_models={"analyser": "grok-build-0.1", "critic": "grok-4.5"},
-        wrapper="okstra-grok-exec.sh",
-        supported_roles=ANALYSIS_ROLES,
-    ),
-    "kimi": ProviderSpec(
-        provider="kimi",
-        display_label="Kimi",
-        models=KIMI,
-        default_models={"analyser": "kimi-k2.7-code", "critic": "kimi-k3"},
-        wrapper="okstra-kimi-exec.sh",
-        supported_roles=ANALYSIS_ROLES,
-    ),
-}
-
-PROVIDER_MAPPINGS = {
-    provider: spec.models for provider, spec in PROVIDERS.items()
-}
-
 # Legacy role-keyed compatibility defaults. Canonical assignments resolve a
 # provider first and then use ProviderSpec.default_models for that role.
 ROLE_DEFAULTS = {
@@ -223,20 +36,6 @@ ROLE_DEFAULTS = {
 }
 
 
-@dataclass
-class ModelAssignment:
-    display: str
-    execution: str
-
-
-class UnknownModelError(ValueError):
-    """raw_value 가 provider mapping 에 등록되어 있지 않을 때 발생."""
-
-
-class UnknownProviderError(ValueError):
-    """Raised when a requested provider is absent from the registry."""
-
-
 def lead_launch_spec(provider: str) -> LeadLaunchSpec:
     """The launch spec for a provider that can lead, or an error naming why not."""
     spec = provider_spec(provider)
@@ -248,13 +47,7 @@ def lead_launch_spec(provider: str) -> LeadLaunchSpec:
 
 
 def bare_lead_launch_argv(provider: str) -> list[str]:
-    """Start this provider's CLI with nothing to do yet.
-
-    `okstra run <lead>` opens the host; the okstra-run skill inside it collects
-    task inputs, exactly as the Claude Code path already works. So there is no
-    prompt and no model to pin here — only the flags that make the session
-    usable to okstra at all.
-    """
+    """Start this provider CLI with only the flags required by Okstra."""
     launch = lead_launch_spec(provider)
     return [launch.executable, *launch.sandbox_waiver]
 
@@ -267,22 +60,15 @@ def lead_launch_argv(
     session_id: str = "",
     waive_sandbox: bool = True,
 ) -> list[str]:
-    """The argv that starts this provider's CLI as the lead for one run.
-
-    The sandbox waiver is applied by default because a sandboxed lead cannot run
-    okstra at all — it reaches neither cmux nor the worker CLIs' own config. The
-    caller still owns telling the user and collecting their answer; passing
-    False produces the un-waived argv so a declined confirmation can show what
-    would otherwise have run.
-    """
+    """Return the argv that starts one provider CLI as the lead for a run."""
     launch = lead_launch_spec(provider)
     argv = [launch.executable]
     if waive_sandbox:
         argv.extend(launch.sandbox_waiver)
     if model:
         argv.extend([launch.model_flag, model])
-    if session_id and launch.session_id_flag:
-        argv.extend([launch.session_id_flag, session_id])
+    if session_id and launch.start_session_id_flag:
+        argv.extend([launch.start_session_id_flag, session_id])
     if launch.prompt_flag:
         argv.append(launch.prompt_flag)
     argv.append(prompt)
@@ -290,12 +76,12 @@ def lead_launch_argv(
 
 
 def provider_spec(provider: str) -> ProviderSpec:
-    """Return one registered provider or fail before assignment/dispatch."""
+    """Return one registered provider or fail before assignment or dispatch."""
     normalized = (provider or "").strip().lower()
     try:
-        return PROVIDERS[normalized]
-    except KeyError as exc:
-        allowed = ", ".join(PROVIDERS)
+        return default_provider_registry().resolve(normalized)
+    except UnknownProviderError as exc:
+        allowed = ", ".join(default_provider_registry().ids())
         raise UnknownProviderError(
             f"unknown provider {provider!r}. Allowed values: {allowed}"
         ) from exc
@@ -303,12 +89,8 @@ def provider_spec(provider: str) -> ProviderSpec:
 
 def provider_ids(role: str | None = None) -> list[str]:
     """Registered provider ids, optionally filtered by functional role."""
-    if not role:
-        return list(PROVIDERS)
-    return [
-        provider for provider, spec in PROVIDERS.items()
-        if role in spec.supported_roles
-    ]
+    registry = default_provider_registry()
+    return list(registry.ids(role if role else None))
 
 
 def provider_supports_role(provider: str, role: str) -> bool:
@@ -318,29 +100,30 @@ def provider_supports_role(provider: str, role: str) -> bool:
 
 def provider_wrappers(role: str | None = None) -> dict[str, str]:
     """Provider-to-wrapper mapping derived from capability entries."""
+    registry = default_provider_registry()
     return {
-        provider: PROVIDERS[provider].wrapper
-        for provider in provider_ids(role)
-        if PROVIDERS[provider].wrapper
+        provider: registry.resolve(provider).wrapper
+        for provider in registry.ids(role if role else None)
+        if registry.resolve(provider).wrapper
     }
 
 
 def provider_default_model(provider: str, role: str) -> Optional[str]:
-    """Resolve a provider's explicit default for one functional role."""
+    """Resolve a provider explicit default for one functional role."""
     return provider_spec(provider).default_models.get(role)
 
 
 def resolve_model_metadata(
     *, provider: str, raw_value: str, default_display: str, default_execution: str,
 ) -> ModelAssignment:
-    """alias → (display, execution). Unchanged contract; mapping values are now
-    ModelSpec instead of tuples."""
+    """Resolve a model alias to its display and execution values."""
     raw_value = (raw_value or "").strip()
-    mapping = PROVIDER_MAPPINGS.get(provider)
-    if raw_value and mapping is not None:
+    mapping = default_provider_registry().providers.get(provider)
+    models = mapping.models if mapping else None
+    if raw_value and models is not None:
         normalized = raw_value.lower()
-        if normalized not in mapping:
-            allowed = ", ".join(sorted(mapping.keys()))
+        if normalized not in models:
+            allowed = ", ".join(sorted(models))
             raise UnknownModelError(
                 f"{provider} model {raw_value!r} is not a supported alias. "
                 f"Allowed values: {allowed}"
@@ -349,24 +132,26 @@ def resolve_model_metadata(
     display = value
     execution = raw_value or default_execution
     normalized = value.strip().lower()
-    if mapping and normalized in mapping:
-        spec = mapping[normalized]
+    if models and normalized in models:
+        spec = models[normalized]
         display, execution = spec.display, spec.execution
     return ModelAssignment(display=display, execution=execution)
 
 
 def picker_options(provider: str) -> list[str]:
     """Picker-exposed aliases for a provider, in catalog insertion order."""
-    mapping = PROVIDER_MAPPINGS.get(provider, {})
-    return [alias for alias, spec in mapping.items() if spec.in_picker]
+    spec = default_provider_registry().providers.get(provider)
+    models = spec.models if spec else {}
+    return [alias for alias, model in models.items() if model.in_picker]
 
 
 def default_model(role: str) -> Optional[str]:
-    """Role → default model alias (env override is the caller's concern)."""
+    """Role-to-default model alias; environment overrides belong to the caller."""
     return ROLE_DEFAULTS.get(role)
 
 
 def catalog_pricing(provider: str) -> dict:
-    """Selectable-model pricing as (input, cached input, output) USD/1M."""
-    mapping = PROVIDER_MAPPINGS.get(provider, {})
-    return {alias: spec.pricing for alias, spec in mapping.items() if spec.pricing is not None}
+    """Selectable-model pricing as input, cached-input, output USD per million."""
+    spec = default_provider_registry().providers.get(provider)
+    models = spec.models if spec else {}
+    return {alias: model.pricing for alias, model in models.items() if model.pricing is not None}

package/runtime/python/okstra_ctl/ports/__init__.py

@@ -0,0 +1,15 @@
+"""Host-facing ports consumed by application use cases."""
+
+from .host import HostAdapter
+from .interaction import InteractionPort
+from .lead_session import LeadSessionPort
+from .usage_accounting import UsageAccountingPort
+from .worker_dispatch import WorkerDispatchPort
+
+__all__ = (
+    "HostAdapter",
+    "InteractionPort",
+    "LeadSessionPort",
+    "UsageAccountingPort",
+    "WorkerDispatchPort",
+)

package/runtime/python/okstra_ctl/ports/host.py

@@ -0,0 +1,32 @@
+"""Composite interface implemented by each host strategy."""
+from __future__ import annotations
+
+from typing import Protocol
+
+from ..domain.host import (
+    HostClaim,
+    HostDescriptor,
+    HostReadiness,
+    HostResolutionContext,
+    HostSessionContext,
+)
+from .interaction import InteractionPort
+from .lead_session import LeadSessionPort
+from .usage_accounting import UsageAccountingPort
+from .worker_dispatch import WorkerDispatchPort
+
+
+class HostAdapter(Protocol):
+    descriptor: HostDescriptor
+
+    def detect(self, context: HostResolutionContext) -> HostClaim | None: ...
+
+    def probe(self, context: HostSessionContext) -> HostReadiness: ...
+
+    def interaction(self) -> InteractionPort: ...
+
+    def lead_session(self) -> LeadSessionPort: ...
+
+    def worker_dispatch(self) -> WorkerDispatchPort: ...
+
+    def usage_accounting(self) -> UsageAccountingPort: ...

package/runtime/python/okstra_ctl/ports/interaction.py

@@ -0,0 +1,15 @@
+"""Interaction boundary exposed by a host adapter."""
+from __future__ import annotations
+
+from typing import Protocol
+
+from ..domain.host import HostSessionContext
+from ..domain.wizard.interaction import InteractionPlan, WizardPrompt
+
+
+class InteractionPort(Protocol):
+    def plan(
+        self,
+        prompt: WizardPrompt,
+        context: HostSessionContext,
+    ) -> InteractionPlan: ...

package/runtime/python/okstra_ctl/ports/lead_session.py

@@ -0,0 +1,25 @@
+"""Lead-session boundary exposed by a host adapter."""
+from __future__ import annotations
+
+from typing import Protocol
+
+from ..domain.host import (
+    HostSessionContext,
+    LeadResumeRequest,
+    LeadSessionPlan,
+    LeadStartRequest,
+)
+
+
+class LeadSessionPort(Protocol):
+    def build_start(
+        self,
+        request: LeadStartRequest,
+        context: HostSessionContext,
+    ) -> LeadSessionPlan: ...
+
+    def build_resume(
+        self,
+        request: LeadResumeRequest,
+        context: HostSessionContext,
+    ) -> LeadSessionPlan: ...

package/runtime/python/okstra_ctl/ports/usage_accounting.py

@@ -0,0 +1,23 @@
+"""Usage-accounting boundary exposed by a host adapter."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class UsageRequest:
+    team_state_path: Path
+    project_root: Path
+    incremental: bool = True
+
+
+@dataclass(frozen=True)
+class UsageSnapshot:
+    source: str
+    payload: dict
+
+
+class UsageAccountingPort(Protocol):
+    def collect(self, request: UsageRequest) -> UsageSnapshot: ...

package/runtime/python/okstra_ctl/ports/worker_dispatch.py

@@ -0,0 +1,32 @@
+"""Worker-dispatch boundary exposed by a host adapter."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, Protocol
+
+
+@dataclass(frozen=True)
+class WorkerDispatchRequest:
+    project_root: Path
+    run_manifest: Path
+    workspace_root: Path | None = None
+    okstra_bin: Path | None = None
+    requested_workers: tuple[str, ...] = ()
+    idle_timeout_seconds: int = 600
+    dispatch_kind: str = "initial"
+    jobs_file: Path | None = None
+
+
+@dataclass(frozen=True)
+class WorkerDispatchPlan:
+    mode: Literal["native-team", "cli-wrapper", "cmux-pane"]
+    request: WorkerDispatchRequest
+    backend_plan: object | None = None
+    adapter_name: str | None = None
+    dispatch_mode: str | None = None
+    relay_contract: str | None = None
+
+
+class WorkerDispatchPort(Protocol):
+    def build_plan(self, request: WorkerDispatchRequest) -> WorkerDispatchPlan: ...

package/runtime/python/okstra_ctl/registry/__init__.py

@@ -0,0 +1,13 @@
+"""Registries that discover and resolve installed Okstra adapters."""
+
+from .provider_registry import (
+    ProviderAdapterContractError,
+    ProviderRegistry,
+    default_provider_registry,
+)
+
+__all__ = (
+    "ProviderAdapterContractError",
+    "ProviderRegistry",
+    "default_provider_registry",
+)

package/runtime/python/okstra_ctl/registry/factory_loader.py

@@ -0,0 +1,32 @@
+"""Safe loader for a provider adapter factory declared in a manifest."""
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+from collections.abc import Callable
+from pathlib import Path
+
+
+class FactoryLoadError(ValueError):
+    """Raised when an adapter factory reference cannot be safely loaded."""
+
+
+def load_relative_factory(manifest_path: Path, factory_ref: str) -> Callable[..., object]:
+    """Load a callable factory without allowing its file to leave the adapter."""
+    file_name, separator, symbol = factory_ref.partition(":")
+    if not separator or not file_name or not symbol:
+        raise FactoryLoadError(f"invalid factory reference: {factory_ref!r}")
+    adapter_root = manifest_path.parent.resolve()
+    module_path = (adapter_root / file_name).resolve()
+    if adapter_root not in module_path.parents or not module_path.is_file():
+        raise FactoryLoadError(f"factory escapes adapter root: {factory_ref!r}")
+    module_name = f"okstra_adapter_{hashlib.sha256(str(module_path).encode()).hexdigest()}"
+    spec = importlib.util.spec_from_file_location(module_name, module_path)
+    if spec is None or spec.loader is None:
+        raise FactoryLoadError(f"cannot load factory module: {module_path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    factory = getattr(module, symbol, None)
+    if not callable(factory):
+        raise FactoryLoadError(f"factory symbol is not callable: {factory_ref!r}")
+    return factory