machinaos 0.0.78 → 0.0.80

package/server/services/plugin/oauth.py

@@ -98,11 +98,7 @@ class OAuthStateStore:
     def cleanup_expired(self) -> int:
         """Remove states older than ``ttl_seconds``. Returns count removed."""
         now = time.time()
-        expired = [
-            state
-            for state, record in self._states.items()
-            if now - record.get("created_at", 0) > self.ttl_seconds
-        ]
+        expired = [state for state, record in self._states.items() if now - record.get("created_at", 0) > self.ttl_seconds]
         for state in expired:
             self._states.pop(state, None)
         if expired:
@@ -180,9 +176,7 @@ class OAuth2PKCEClient(ABC):
         scopes: Optional[List[str]] = None,
     ) -> None:
         if not self.provider:
-            raise ValueError(
-                f"{type(self).__name__} must set the ``provider`` ClassVar"
-            )
+            raise ValueError(f"{type(self).__name__} must set the ``provider`` ClassVar")
         self.client_id = client_id
         self.client_secret = client_secret
         self.redirect_uri = redirect_uri
@@ -207,11 +201,14 @@ class OAuth2PKCEClient(ABC):
         code_verifier = _generate_code_verifier()
         code_challenge = _generate_code_challenge(code_verifier)
 
-        self.state_store.put(state, {
-            "code_verifier": code_verifier,
-            "redirect_uri": self.redirect_uri,
-            "data": state_data or {},
-        })
+        self.state_store.put(
+            state,
+            {
+                "code_verifier": code_verifier,
+                "redirect_uri": self.redirect_uri,
+                "data": state_data or {},
+            },
+        )
 
         params = {
             "response_type": "code",
@@ -240,9 +237,7 @@ class OAuth2PKCEClient(ABC):
         in the header. Public clients put ``client_id`` in the body.
         """
         if self.client_secret:
-            credentials = base64.b64encode(
-                f"{self.client_id}:{self.client_secret}".encode()
-            ).decode()
+            credentials = base64.b64encode(f"{self.client_id}:{self.client_secret}".encode()).decode()
             return {}, {"Authorization": f"Basic {credentials}"}
         return {"client_id": self.client_id}, {}
 
@@ -266,7 +261,9 @@ class OAuth2PKCEClient(ABC):
         try:
             async with httpx.AsyncClient(timeout=30.0) as client:
                 response = await client.post(
-                    self.token_endpoint, data=body, headers=headers,
+                    self.token_endpoint,
+                    data=body,
+                    headers=headers,
                 )
         except httpx.HTTPError as exc:
             logger.error(f"[{self.provider}] HTTP error during token exchange: {exc}")
@@ -276,7 +273,8 @@ class OAuth2PKCEClient(ABC):
             error_data = response.json() if response.text else {}
             logger.error(
                 f"[{self.provider}] Token exchange failed",
-                status=response.status_code, error=error_data,
+                status=response.status_code,
+                error=error_data,
             )
             return {
                 "success": False,
@@ -306,7 +304,9 @@ class OAuth2PKCEClient(ABC):
         try:
             async with httpx.AsyncClient(timeout=30.0) as client:
                 response = await client.post(
-                    self.token_endpoint, data=body, headers=headers,
+                    self.token_endpoint,
+                    data=body,
+                    headers=headers,
                 )
         except httpx.HTTPError as exc:
             logger.error(f"[{self.provider}] HTTP error during token refresh: {exc}")
@@ -329,7 +329,9 @@ class OAuth2PKCEClient(ABC):
         }
 
     async def revoke_token(
-        self, token: str, token_type: str = "access_token",
+        self,
+        token: str,
+        token_type: str = "access_token",
     ) -> Dict[str, Any]:
         """Revoke an access or refresh token (best-effort).
 
@@ -348,7 +350,9 @@ class OAuth2PKCEClient(ABC):
         try:
             async with httpx.AsyncClient(timeout=30.0) as client:
                 response = await client.post(
-                    self.revocation_endpoint, data=body, headers=headers,
+                    self.revocation_endpoint,
+                    data=body,
+                    headers=headers,
                 )
         except httpx.HTTPError as exc:
             logger.error(f"[{self.provider}] HTTP error during token revoke: {exc}")

package/server/services/plugin/operation.py

@@ -32,7 +32,7 @@ class OperationSpec:
     name: str
     method: Callable[..., Awaitable[Any]]
     routing: Optional[Routing] = None
-    cost: Optional[Dict[str, Any]] = None          # {"usage": "gmail_send", "count": 1}
+    cost: Optional[Dict[str, Any]] = None  # {"usage": "gmail_send", "count": 1}
     annotations: Dict[str, Any] = field(default_factory=dict)
 
 

package/server/services/plugin/polling.py

@@ -46,7 +46,7 @@ Out of scope (commit-stage)
 from __future__ import annotations
 
 import asyncio
-from typing import Any, Callable, ClassVar, Dict, Optional, Set, Tuple
+from typing import Any, Callable, ClassVar, Dict, Set, Tuple
 
 from core.logging import get_logger
 from services.plugin.trigger import TriggerNode
@@ -97,9 +97,7 @@ class PollingTriggerNode(TriggerNode, abstract=True):
         """
         raise NotImplementedError
 
-    async def fetch_ids(
-        self, service: Any, params: Dict[str, Any]
-    ) -> Set[str]:
+    async def fetch_ids(self, service: Any, params: Dict[str, Any]) -> Set[str]:
         """Return the current set of visible IDs for one poll cycle.
 
         Called once for the baseline pass at loop start, then once per
@@ -108,9 +106,7 @@ class PollingTriggerNode(TriggerNode, abstract=True):
         """
         raise NotImplementedError
 
-    async def fetch_detail(
-        self, service: Any, msg_id: str, params: Dict[str, Any]
-    ) -> Dict[str, Any]:
+    async def fetch_detail(self, service: Any, msg_id: str, params: Dict[str, Any]) -> Dict[str, Any]:
         """Fetch the full event payload for one ID.
 
         Called once per new ID per cycle. The returned dict goes
@@ -119,9 +115,7 @@ class PollingTriggerNode(TriggerNode, abstract=True):
         """
         raise NotImplementedError
 
-    async def post_emit(
-        self, service: Any, msg_id: str, params: Dict[str, Any]
-    ) -> None:
+    async def post_emit(self, service: Any, msg_id: str, params: Dict[str, Any]) -> None:
         """Optional side effect AFTER the payload was enqueued.
 
         Default no-op. Override for "mark-as-read" or similar
@@ -166,22 +160,131 @@ class PollingTriggerNode(TriggerNode, abstract=True):
             value = self.default_poll_interval
         return max(lo, min(hi, value))
 
-    def _build_poll_coroutine(
-        self, node_id: str, params: Dict[str, Any]
-    ) -> Callable[[asyncio.Queue, Callable[[], bool]], Any]:
+    # ---- Wave 12 C2: per-cycle Temporal activity --------------------------
+    #
+    # The asyncio coroutine version above feeds the legacy
+    # ``setup_polling_trigger`` collector/processor task pair (dies on
+    # FastAPI restart). The Temporal-durable version below — yielded by
+    # :meth:`as_poll_activity` — does ONE cycle and returns events,
+    # called per ``workflow.sleep`` tick in
+    # :class:`services.temporal.polling_trigger_workflow.PollingTriggerWorkflow`.
+    # The seen-id baseline survives via workflow state (carried across
+    # ``continueAsNew``) rather than living inside the asyncio task.
+
+    @classmethod
+    def as_poll_activity(cls):
+        """Return a ``@activity.defn`` wrapping one poll cycle.
+
+        Stable activity name: ``poll.{type}.v{version}``.
+
+        Activity payload (in)::
+
+            {
+                "node_id": str,
+                "params": Dict[str, Any],
+                "seen_ids": List[str],   # provider-side IDs from prior cycle
+                "baseline_only": bool,    # True on the first call after start
+            }
+
+        Activity result (out)::
+
+            {
+                "events": List[Dict],     # NEW event payloads this cycle
+                "seen_ids": List[str],    # union of prior seen + current
+            }
+
+        Determinism: every operation runs inside the activity (network
+        I/O, mutable state) — the workflow body only sees the serialised
+        result so replay stays deterministic. Per-cycle errors raise
+        out of the activity; the workflow's ``RetryPolicy`` / try-except
+        owns retry semantics.
+        """
+        from temporalio import activity
+
+        activity_name = f"poll.{cls.type}.v{cls.version}"
+
+        @activity.defn(name=activity_name)
+        async def _poll_cycle_activity(payload: Dict[str, Any]) -> Dict[str, Any]:
+            node_id = payload.get("node_id", "")
+            params = payload.get("params", {}) or {}
+            prior_seen: Set[str] = set(payload.get("seen_ids") or [])
+            baseline_only = bool(payload.get("baseline_only"))
+
+            instance = cls()
+            try:
+                service = await instance.setup_service(params)
+            except Exception as exc:  # noqa: BLE001
+                logger.error(
+                    "Polling activity setup failed",
+                    node_id=node_id,
+                    node_type=cls.type,
+                    error=str(exc),
+                )
+                raise
+
+            current = await instance.fetch_ids(service, params)
+
+            if baseline_only:
+                # First call after workflow start: establish the seen
+                # baseline without emitting anything. Matches the
+                # pre-Temporal collector's baseline pass.
+                return {"events": [], "seen_ids": list(current)}
+
+            new_ids = current - prior_seen
+            events: list[Dict[str, Any]] = []
+            for msg_id in new_ids:
+                try:
+                    detail = await instance.fetch_detail(service, msg_id, params)
+                except Exception as exc:  # noqa: BLE001
+                    logger.warning(
+                        "Polling activity fetch_detail failed; skipping id",
+                        node_id=node_id,
+                        node_type=cls.type,
+                        msg_id=msg_id,
+                        error=str(exc),
+                    )
+                    continue
+                # The workflow needs a stable event.id for cross-cycle
+                # dedup. Fall back to the provider id when fetch_detail
+                # doesn't supply one.
+                if "id" not in detail:
+                    detail["id"] = msg_id
+                events.append(detail)
+                # post_emit side effect (e.g. mark-as-read). Failures
+                # MUST NOT block the next emit or kill the cycle —
+                # mirror the legacy coroutine semantics.
+                try:
+                    await instance.post_emit(service, msg_id, params)
+                except Exception:
+                    pass
+
+            # OOM fix: bound ``seen_ids`` to what the provider currently
+            # reports as visible — old IDs that have dropped off the
+            # provider's window (archived / deleted / aged out) fall
+            # out of seen too. Pre-fix this was ``prior_seen | current``
+            # which grew forever (every poll appended new IDs; nothing
+            # ever got evicted). At Gmail's ~100 msgs/day cadence the
+            # set hit ~36K entries in a year — ~1.4MB just for IDs,
+            # serialised through Temporal payload on every cycle. Now
+            # bounded by the provider's natural window size.
+            return {"events": events, "seen_ids": list(current)}
+
+        return _poll_cycle_activity
+
+    def _build_poll_coroutine(self, node_id: str, params: Dict[str, Any]) -> Callable[[asyncio.Queue, Callable[[], bool]], Any]:
         """Return the bound poll coroutine the deployment manager
         consumes. Closes over ``self``, ``node_id``, and ``params``.
         """
 
-        async def poll(
-            queue: asyncio.Queue, is_running_fn: Callable[[], bool]
-        ) -> None:
+        async def poll(queue: asyncio.Queue, is_running_fn: Callable[[], bool]) -> None:
             try:
                 service = await self.setup_service(params)
             except Exception as exc:  # noqa: BLE001 -- single setup failure
                 logger.error(
                     "Polling trigger setup failed",
-                    node_id=node_id, node_type=self.type, error=str(exc),
+                    node_id=node_id,
+                    node_type=self.type,
+                    error=str(exc),
                 )
                 return
 
@@ -197,12 +300,16 @@ class PollingTriggerNode(TriggerNode, abstract=True):
                 seen = await self.fetch_ids(service, params)
                 logger.info(
                     "Polling trigger baseline established",
-                    node_id=node_id, node_type=self.type, seen=len(seen),
+                    node_id=node_id,
+                    node_type=self.type,
+                    seen=len(seen),
                 )
             except Exception as exc:  # noqa: BLE001
                 logger.warning(
                     "Polling trigger baseline failed; treating all as new",
-                    node_id=node_id, node_type=self.type, error=str(exc),
+                    node_id=node_id,
+                    node_type=self.type,
+                    error=str(exc),
                 )
 
             cycle = 0
@@ -215,18 +322,23 @@ class PollingTriggerNode(TriggerNode, abstract=True):
                     current = await self.fetch_ids(service, params)
                     new_ids = current - seen
                     if not new_ids:
+                        # OOM fix: even when nothing new arrives we
+                        # still rebase ``seen`` to ``current`` so old
+                        # IDs that dropped off the provider's window
+                        # don't linger forever.
+                        seen = set(current)
                         continue
                     logger.debug(
                         "Polling trigger cycle",
-                        node_id=node_id, node_type=self.type, cycle=cycle,
-                        current=len(current), seen=len(seen),
+                        node_id=node_id,
+                        node_type=self.type,
+                        cycle=cycle,
+                        current=len(current),
+                        seen=len(seen),
                         new=len(new_ids),
                     )
                     for msg_id in new_ids:
-                        seen.add(msg_id)
-                        payload = await self.fetch_detail(
-                            service, msg_id, params
-                        )
+                        payload = await self.fetch_detail(service, msg_id, params)
                         await queue.put(payload)
                         # post_emit failure must NOT block the next emit
                         # nor kill the loop; mirrors pre-migration
@@ -235,12 +347,25 @@ class PollingTriggerNode(TriggerNode, abstract=True):
                             await self.post_emit(service, msg_id, params)
                         except Exception:
                             pass
+                    # OOM fix: rebase ``seen`` to the provider's current
+                    # window. Pre-fix this added every new ID to ``seen``
+                    # forever (``seen.add(msg_id)`` inside the loop, no
+                    # eviction). Long-running pollers (Gmail with the
+                    # default 60s interval) accumulated tens of thousands
+                    # of entries over weeks/months. Now bounded by the
+                    # provider's natural window size — items that have
+                    # been emitted are still in ``current`` until they
+                    # age/archive out, at which point dropping them is
+                    # correct (the provider will never re-surface them
+                    # under the same filter).
+                    seen = set(current)
                 except asyncio.CancelledError:
                     raise
                 except Exception as exc:  # noqa: BLE001 -- per-cycle isolation
                     logger.error(
                         "Polling trigger cycle error; retrying next interval",
-                        node_id=node_id, node_type=self.type,
+                        node_id=node_id,
+                        node_type=self.type,
                         error=str(exc),
                     )
 

package/server/services/plugin/registry.py

@@ -78,17 +78,65 @@ class IdempotentRegistry(Generic[K, V]):
         self._on_register = on_register
 
     def register(self, key: K, value: V) -> None:
-        """Add ``key -> value``. Idempotent on identity; raises on conflict."""
+        """Add ``key -> value``. Idempotent on equality; raises on conflict.
+
+        Three equivalence checks (any match = idempotent re-register):
+
+        1. ``existing == value`` — covers strings / ints / dataclasses /
+           dicts (content-equal even on reload) and singleton instances
+           cached across imports.
+        2. **Reload tolerance for callables**: same fully-qualified
+           name (``__module__`` + ``__qualname__``) means the same
+           source-level function reloaded under fresh identity.
+           ``importlib.reload(module)`` constructs new function objects
+           that compare unequal under Python's identity-based
+           ``function.__eq__``; without this branch the
+           self-containment reload tests would break for every plugin
+           that registers a wrapper closure.
+        3. **Reload tolerance for classes**: same ``__module__`` +
+           ``__qualname__`` for class objects (same reason).
+
+        Genuinely conflicting registrations (different values, different
+        names) still raise ``ValueError`` at import time.
+        """
         existing = self._items.get(key)
-        if existing is not None and existing is not value:
+        if existing is not None and not self._values_equivalent(existing, value):
             raise ValueError(
-                f"{self._name}: {key!r} is already registered by "
-                f"{_qual(existing)}; refusing to overwrite with {_qual(value)}"
+                f"{self._name}: {key!r} is already registered by " f"{_qual(existing)}; refusing to overwrite with {_qual(value)}"
             )
         self._items[key] = value
         if self._on_register is not None:
             self._on_register(key, value)
 
+    @staticmethod
+    def _values_equivalent(existing: object, new: object) -> bool:
+        """True iff ``existing`` and ``new`` are the same registration
+        for idempotency purposes. See :meth:`register` docstring."""
+        # Content equality first (strings, dicts, dataclasses, singletons
+        # cached across imports). Catches the bulk of cases.
+        try:
+            if existing == new:
+                return True
+        except Exception:  # noqa: BLE001 — exotic types with broken __eq__
+            pass
+
+        # Reload tolerance: callable / class objects re-defined under a
+        # fresh module-level identity still count as the "same"
+        # registration when their fully-qualified name matches.
+        existing_module = getattr(existing, "__module__", None)
+        new_module = getattr(new, "__module__", None)
+        existing_qualname = getattr(existing, "__qualname__", None)
+        new_qualname = getattr(new, "__qualname__", None)
+        if (
+            existing_qualname is not None
+            and new_qualname is not None
+            and existing_module == new_module
+            and existing_qualname == new_qualname
+        ):
+            return True
+
+        return False
+
     def get(self, key: K) -> Optional[V]:
         return self._items.get(key)
 

package/server/services/plugin/routing.py

@@ -61,6 +61,7 @@ class Routing(BaseModel):
 # ---------------------------------------------------------------------------
 # Template interpolation
 
+
 def _resolve_template(value: Any, env: Dict[str, Any]) -> Any:
     """Resolve ``={{expr}}`` templates against ``env``. Non-string values
     pass through. Supports dotted paths — ``params.maxResults``."""
@@ -94,6 +95,7 @@ def _resolve_dict(d: Dict[str, Any], env: Dict[str, Any]) -> Dict[str, Any]:
 # ---------------------------------------------------------------------------
 # post_receive strategies
 
+
 def _strategy_root_property(data: Any, action: PostReceiveAction) -> Any:
     if not action.property or not isinstance(data, dict):
         return data
@@ -114,9 +116,7 @@ def _strategy_limit(data: Any, action: PostReceiveAction) -> Any:
 def _strategy_filter(data: Any, action: PostReceiveAction) -> Any:
     if not isinstance(data, list) or not action.where:
         return data
-    return [item for item in data if all(
-        isinstance(item, dict) and item.get(k) == v for k, v in action.where.items()
-    )]
+    return [item for item in data if all(isinstance(item, dict) and item.get(k) == v for k, v in action.where.items())]
 
 
 def _strategy_set(data: Any, action: PostReceiveAction) -> Any:
@@ -125,8 +125,7 @@ def _strategy_set(data: Any, action: PostReceiveAction) -> Any:
     if isinstance(data, dict):
         return {**data, **action.set_fields}
     if isinstance(data, list):
-        return [{**item, **action.set_fields} if isinstance(item, dict) else item
-                for item in data]
+        return [{**item, **action.set_fields} if isinstance(item, dict) else item for item in data]
     return data
 
 
@@ -141,6 +140,7 @@ POST_RECEIVE_STRATEGIES = {
 # ---------------------------------------------------------------------------
 # Execution
 
+
 async def execute_routing(
     routing: Routing,
     *,
@@ -164,10 +164,7 @@ async def execute_routing(
 
     kwargs: Dict[str, Any] = {"headers": headers, "params": qs}
     if req.body is not None:
-        body_resolved = (
-            _resolve_dict(req.body, env) if isinstance(req.body, dict) else
-            _resolve_template(req.body, env)
-        )
+        body_resolved = _resolve_dict(req.body, env) if isinstance(req.body, dict) else _resolve_template(req.body, env)
         if req.body_encoding == "form":
             kwargs["data"] = body_resolved
         else:

package/server/services/plugin/scaling.py

@@ -20,20 +20,29 @@ class TaskQueue:
     and provision a worker pool in ``services/temporal/worker.py``.
     """
 
-    DEFAULT = "machina-default"     # catch-all
-    REST_API = "rest-api"           # lightweight HTTP calls (gmail, brave, twitter)
-    AI_HEAVY = "ai-heavy"           # long-running LLM + agent loops
-    CODE_EXEC = "code-exec"         # python/js/ts sandboxed execution
-    TRIGGERS_POLL = "triggers-poll" # polling triggers (long-lived)
+    DEFAULT = "machina-default"  # catch-all
+    REST_API = "rest-api"  # lightweight HTTP calls (gmail, brave, twitter)
+    AI_HEAVY = "ai-heavy"  # long-running LLM + agent loops
+    CODE_EXEC = "code-exec"  # python/js/ts sandboxed execution
+    TRIGGERS_POLL = "triggers-poll"  # polling triggers (long-lived)
     TRIGGERS_EVENT = "triggers-event"  # event-waiter triggers (long-lived)
-    ANDROID = "android"             # ADB / relay ops
-    BROWSER = "browser"             # agent-browser, Playwright
-    MESSAGING = "messaging"         # whatsapp / telegram / twitter send
+    ANDROID = "android"  # ADB / relay ops
+    BROWSER = "browser"  # agent-browser, Playwright
+    MESSAGING = "messaging"  # whatsapp / telegram / twitter send
 
-    ALL = frozenset({
-        DEFAULT, REST_API, AI_HEAVY, CODE_EXEC,
-        TRIGGERS_POLL, TRIGGERS_EVENT, ANDROID, BROWSER, MESSAGING,
-    })
+    ALL = frozenset(
+        {
+            DEFAULT,
+            REST_API,
+            AI_HEAVY,
+            CODE_EXEC,
+            TRIGGERS_POLL,
+            TRIGGERS_EVENT,
+            ANDROID,
+            BROWSER,
+            MESSAGING,
+        }
+    )
 
 
 @dataclass(frozen=True)
@@ -47,11 +56,20 @@ class RetryPolicy:
     backoff_coefficient: float = 2.0
     maximum_interval: timedelta = timedelta(seconds=60)
     maximum_attempts: int = 3
-    non_retryable_error_types: Sequence[str] = field(default_factory=lambda: (
-        "ValidationError",
-        "PermissionDeniedError",
-        "InvalidParametersError",
-    ))
+    non_retryable_error_types: Sequence[str] = field(
+        default_factory=lambda: (
+            "ValidationError",
+            "PermissionDeniedError",
+            "InvalidParametersError",
+            # Wave 12 A2: NodeUserError is the canonical "user-correctable
+            # failure" exception (missing input, missing credential, API
+            # rejected the payload). Retrying it just burns attempts since
+            # the underlying input won't fix itself. Plugins that raise
+            # NodeUserError fail fast; the framework surfaces the message
+            # to the user / agent loop without traceback noise.
+            "NodeUserError",
+        )
+    )
 
     def to_temporal(self):
         """Lazy import — only called inside the Temporal worker."""
@@ -74,5 +92,5 @@ DEFAULT_RETRY = RetryPolicy()
 # Kind-specific defaults — picked up when a subclass doesn't override.
 ACTION_START_TO_CLOSE = timedelta(minutes=10)
 AI_START_TO_CLOSE = timedelta(minutes=30)
-TRIGGER_START_TO_CLOSE = timedelta(hours=24)     # long-lived
+TRIGGER_START_TO_CLOSE = timedelta(hours=24)  # long-lived
 CODE_START_TO_CLOSE = timedelta(minutes=5)

package/server/services/plugin/service_factories.py

@@ -0,0 +1,95 @@
+"""Plugin-owned registry of service-factory callables for the DI container.
+
+Closes the two remaining cross-plugin top-level imports in
+``core/container.py``:
+
+  - ``from nodes.location._service import MapsService``  (line 25)
+  - ``from nodes.android._dispatcher import AndroidService``  (line 30)
+
+Both made the framework's DI container code know about specific
+plugins' implementation classes — direct violation of the
+"framework knows no plugin names" rule.
+
+Pattern (matches the established Wave-11.I plugin-self-registration
+shape; same as ``register_filter_builder`` /
+``register_poll_coroutine_factory`` / ``register_ws_handlers`` /
+``register_canary_trigger_type`` / ``register_social_send_handler`` /
+``register_shutdown_hook``):
+
+1. Plugin's ``__init__.py`` imports its service class from ``_service.py``
+   (intra-plugin, fine) and calls
+   ``register_service_factory("<name>", ServiceClass)``.
+2. The container's provider declaration references a lazy lookup
+   function — :func:`get_service_factory` — instead of the concrete
+   class. ``providers.Factory`` / ``providers.Singleton`` calls the
+   wrapper function with its declared kwargs; the wrapper looks up
+   the registered factory and instantiates.
+3. Lookup happens at **instantiation time** (first ``container.foo()``
+   call), not at class-definition time, so plugin import ordering
+   isn't a constraint — plugin auto-discovery on startup populates
+   the registry before any service is first resolved.
+
+Factory signature
+-----------------
+
+The "factory" is typically the class itself (calling it constructs
+the instance). Any zero-or-more-keyword-arg callable that returns
+the service instance is acceptable.
+
+::
+
+    factory(**kwargs) -> ServiceInstance
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from services.plugin.registry import IdempotentRegistry
+
+
+ServiceFactory = Callable[..., Any]
+
+
+_REGISTRY: IdempotentRegistry[str, ServiceFactory] = IdempotentRegistry("service_factory")
+
+
+def register_service_factory(name: str, factory: ServiceFactory) -> None:
+    """Publish a service factory for the DI container.
+
+    Idempotent on re-import (same callable / class for the same name
+    is a no-op). A different factory for an existing name raises
+    ``ValueError`` to surface plugin namespace collisions at import time.
+
+    Args:
+        name: Lower-case service identifier (``"maps"``, ``"android"``,
+            ...). The container's provider declaration references this
+            name via :func:`get_service_factory`.
+        factory: The service class (or any callable taking the
+            provider's declared kwargs) that constructs the service
+            instance.
+    """
+    _REGISTRY.register(name, factory)
+
+
+def get_service_factory(name: str) -> Optional[ServiceFactory]:
+    """Return the factory for ``name``, or ``None`` if unregistered.
+
+    Container providers wrap this in a lazy thunk that surfaces a
+    clear "service not registered" error if a required plugin failed
+    to load, instead of silently producing ``None``.
+    """
+    return _REGISTRY.get(name)
+
+
+def registered_service_names() -> frozenset[str]:
+    """Return an immutable snapshot of registered service identifiers."""
+    return frozenset(_REGISTRY.keys())
+
+
+__all__ = [
+    "register_service_factory",
+    "get_service_factory",
+    "registered_service_names",
+    "ServiceFactory",
+]