froid-loop 0.11.1__py3-none-any.whl

froid_loop/plugins/model.py

@@ -0,0 +1,296 @@
+"""Data model for the froid-loop plugin system.
+
+A plugin extends the orchestrator without touching the core loop. Every plugin
+is a ``plugin.toml`` manifest (metadata, declarative out-of-process hooks, a
+settings schema, optional in-process Python). Data-only plugins need no code.
+
+This module holds the immutable shapes the manifest parses into plus the
+``Plugin`` base class that a trusted in-process plugin subclasses. It mirrors
+the proven dataclass-as-data style of ``engines/plugin.py`` and
+``adapters/profile.py`` — parsing/validation lives in ``manifest.py``,
+discovery in ``loader.py``, trust in ``trust.py`` and aggregation in
+``registry.py``. Nothing here reaches into the run loop; the hook bus that
+calls into a plugin is wired in a later phase.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .context import HookContext
+
+# The framework's current plugin-API version. A manifest declares the api_version
+# it was written against; the loader compares it against SUPPORTED_API. Bumping
+# this set (never removing without a major) is how the API evolves.
+API_VERSION = 1
+SUPPORTED_API: frozenset[int] = frozenset({1})
+
+# Permitted [[settings]] kinds. "select" carries an options list; the rest are
+# scalars. Kept deliberately small — the settings pillar (Phase 1) maps these to
+# widget hints.
+SETTING_TYPES = {"bool", "int", "float", "str", "select"}
+
+# Stages at which a plugin-provided workflow may inject an extra agent session
+# (Phase 4). Deliberately small + conservative: all fire *inside* the unit's
+# live worktree with the dev/review work already on disk, so an injected session
+# sees the real tree. post_review_result fires only when the orchestrator review
+# loop actually runs (review.trigger="recommended" skips it on most stories);
+# pre_commit_gate fires unconditionally just before commit on every path —
+# review, skip, and budget-rescue alike — so a gate session evaluates the exact
+# tree about to commit. Other stages either lack a worktree (run-boundary) or
+# run after teardown (post_story restores the main checkout), so a session there
+# would target the wrong tree — they are intentionally excluded.
+WORKFLOW_STAGES = frozenset({"post_dev_phase", "post_review_result", "pre_commit_gate"})
+
+# Roles a workflow session may run as — the engine's two adapters. A workflow
+# names one so it reuses that role's resolved adapter config (model, timeout).
+WORKFLOW_ROLES = frozenset({"dev", "review"})
+
+# Where a manifest was discovered, in overlay precedence order. Recorded so the
+# loader can treat an api_version mismatch as a hard error for builtins but a
+# skip-with-warning for third-party plugins.
+PLUGIN_SOURCES = ("builtin", "entry_point", "project")
+
+
+class PluginError(Exception):
+    """Raised on a malformed manifest, an unknown plugin, or an unsupported
+    builtin api_version. Mirrors ProfileError."""
+
+
+@dataclass(frozen=True)
+class HookSpec:
+    """A declarative, out-of-process hook bound to a lifecycle stage.
+
+    ``stage`` is the ``[hooks.<stage>]`` table key. ``cmd`` is a shell command
+    template that may use ``{scripts}`` (expanded to the plugin's script dir).
+    A ``blocking`` hook's non-zero exit vetoes the unit (defer); a non-blocking
+    hook is advisory (logged). Stage names are not validated here — the stage
+    map is owned by the hook bus, wired in a later phase.
+    """
+
+    stage: str
+    cmd: str = ""
+    timeout_sec: int = 120
+    blocking: bool = False
+    # Blocking-hook failure policy. fail_open (default): a hook *error* (timeout,
+    # missing interpreter) lets the run survive; only a clean non-zero exit
+    # vetoes. fail_closed: any failure vetoes (defer). Consumed by the bus later.
+    fail_closed: bool = False
+
+
+@dataclass(frozen=True)
+class SettingSpec:
+    """One plugin-contributed setting, consumed by the settings pillar.
+
+    The vocabulary intentionally matches the core settings ``_Field``: a key, a
+    kind, a default, help text, and (for ``select``) an options list plus
+    optional numeric bounds. Stored under ``[plugins.<name>]`` in policy.toml.
+    """
+
+    key: str
+    type: str
+    default: Any = None
+    help: str = ""
+    options: tuple[str, ...] = ()
+    label: str = ""
+    min: int | None = None
+    max: int | None = None
+
+
+@dataclass(frozen=True)
+class WorkflowSpec:
+    """A plugin-provided workflow: an extra agent session injected at a lifecycle
+    stage (the ``[provides]`` surface, implemented in Phase 4).
+
+    A workflow is the conservative form of custom orchestration the plan settled
+    on — no new pipeline stage, just an extra session run through the engine's
+    generic ``_run_session`` path at an allowlisted ``stage`` (see
+    WORKFLOW_STAGES). ``role`` selects which adapter runs it (WORKFLOW_ROLES);
+    ``prompt`` is the agent prompt template, expanding ``{story_key}``,
+    ``{run_id}`` and ``{scripts}`` (the plugin's script dir). A ``blocking``
+    workflow whose session does not complete defers the unit (it routes through
+    the engine's existing defer primitive); a non-blocking one is advisory.
+
+    Settings overlay (manifest value is the default; a setting tunes it per run):
+    a plugin's resolved settings can override two of these fields by naming
+    convention, read in ``PluginRegistry.workflows_for``/``workflow_stages``:
+
+      * ``<name>_enabled`` (bool) — when explicitly ``false``, the step is
+        dropped entirely (no session injected, the stage falls out of the O(1)
+        injection guard if every step there is off).
+      * ``<name>_blocking`` (bool) — overrides this spec's ``blocking`` flag,
+        flipping the advisory/defer behaviour without editing the manifest.
+
+    ``<name>`` is this workflow's ``name``; declare matching ``[[settings]]`` so
+    operators can flip them from ``[plugins.<plugin>]`` in policy.toml. Absent
+    settings preserve the manifest values exactly — a plugin that declares none
+    is byte-identical to a plugin system without the overlay.
+    """
+
+    name: str
+    stage: str
+    role: str = "dev"
+    prompt: str = ""
+    blocking: bool = False
+
+
+@dataclass(frozen=True)
+class PythonSpec:
+    """Optional in-process module. Its presence makes the plugin trust-gated:
+    the module is never imported unless the plugin is in ``[plugins] enabled``.
+
+    ``module`` is a plugin-relative file (resolved against the plugin's script
+    dir); ``cls`` is the ``Plugin`` subclass to instantiate (defaults to
+    ``Plugin``).
+    """
+
+    module: str
+    cls: str = "Plugin"
+
+
+@dataclass(frozen=True)
+class PluginManifest:
+    """A parsed ``plugin.toml``. Immutable; the single inter-module contract.
+
+    ``scripts_dir`` is the plugin's on-disk directory (its ``{scripts}`` root),
+    set by the loader. ``source`` records discovery origin (see PLUGIN_SOURCES).
+    """
+
+    name: str
+    version: str = "0.0.0"
+    api_version: int = API_VERSION
+    description: str = ""
+    author: str = ""
+    hooks: tuple[HookSpec, ...] = ()
+    settings: tuple[SettingSpec, ...] = ()
+    python: PythonSpec | None = None
+    # custom orchestration items a plugin contributes: extra agent sessions
+    # injected at a lifecycle stage (parsed from [workflows.<name>] tables).
+    workflows: tuple[WorkflowSpec, ...] = ()
+    # extra gitignored paths to seed into a per-unit worktree, mirroring the
+    # engine plugin (seed_files = literal project-relative paths, seed_globs =
+    # patterns expanded against the main repo). Consumed by worktree priming.
+    seed_files: tuple[str, ...] = ()
+    seed_globs: tuple[str, ...] = ()
+    # ordering across plugins at a shared stage: lower runs first, then load order.
+    priority: int = 0
+    scripts_dir: str = ""
+    source: str = "project"
+
+    def render(self, template: str) -> str:
+        """Expand ``{scripts}`` in a command template to this plugin's dir."""
+        return template.replace("{scripts}", self.scripts_dir)
+
+    def hook_for(self, stage: str) -> HookSpec | None:
+        for hook in self.hooks:
+            if hook.stage == stage:
+                return hook
+        return None
+
+    def setting_defaults(self) -> dict[str, Any]:
+        return {s.key: s.default for s in self.settings}
+
+    def workflows_for(self, stage: str) -> tuple[WorkflowSpec, ...]:
+        return tuple(w for w in self.workflows if w.stage == stage)
+
+
+class Plugin:
+    """Base class for a trusted in-process plugin.
+
+    A ``[python]`` manifest names a subclass; the registry instantiates it with
+    the parsed manifest and the plugin's resolved settings (defaults overlaid by
+    ``[plugins.<name>]`` in policy.toml). Hook-dispatch methods are added when
+    the bus is wired in a later phase — for now the base simply carries context,
+    so a folder-dropped plugin that is enabled can be constructed and inspected
+    without yet being able to affect a run.
+
+    Subclasses MUST NOT do expensive or side-effecting work in ``__init__``;
+    construction happens at registry build time and a raised exception disables
+    the instance (failure isolation).
+
+    Hook dispatch: the bus calls ``hook(stage, ctx)``, which routes to an
+    ``on_<stage>(ctx)`` method if the subclass defines one (else a no-op). A
+    handler observes ``ctx`` (read-only fields), mutates the whitelisted
+    ``proposed_*`` fields / ``ctx.shared``, and/or calls ``ctx.veto(action,
+    reason)``. Set the class attribute ``fail_closed = True`` to make a raised
+    exception veto (defer) the unit instead of failing open.
+    """
+
+    # opt-in: a handler raising disables the instance either way (failure
+    # isolation); fail_closed additionally vetoes (defers) the current unit.
+    fail_closed: bool = False
+
+    def __init__(self, manifest: PluginManifest, settings: dict[str, Any]):
+        self.manifest = manifest
+        self.settings = settings
+
+    @property
+    def name(self) -> str:
+        return self.manifest.name
+
+    def validate(self, policy: Any) -> None:
+        """Self-validate the plugin's resolved settings against the run policy.
+
+        Called once at registry-build time (before any stage fires). A plugin
+        raises ``PluginError`` here to reject an incompatible configuration —
+        e.g. a coupling between a plugin setting and a core policy field that a
+        flat per-key schema can't express (the engine plugin's
+        editor_mode↔scm.isolation coupling). This is a deliberate config
+        rejection, not a plugin bug, so the registry lets it propagate and the
+        run fails fast rather than being isolated out. The default is a no-op."""
+
+    def hook(self, stage: str, ctx: "HookContext") -> None:
+        """Route a stage to its ``on_<stage>`` handler, if defined. The bus wraps
+        this call for failure isolation, so a subclass handler may raise freely."""
+        handler = getattr(self, f"on_{stage}", None)
+        if handler is not None:
+            handler(ctx)
+
+    def __repr__(self) -> str:  # pragma: no cover - debug aid
+        return f"<Plugin {self.manifest.name!r} v{self.manifest.version}>"
+
+
+@dataclass(frozen=True)
+class LoadedPlugin:
+    """A manifest plus its trust/resolution outcome, as the registry holds it.
+
+    ``instance`` is a constructed ``Plugin`` for an enabled, trusted ``[python]``
+    plugin; ``None`` for a data-only/declarative plugin, an untrusted one (has
+    ``[python]`` but isn't allowlisted), or one whose construction raised.
+    ``disabled`` marks an instance that errored and was isolated out.
+    """
+
+    manifest: PluginManifest
+    instance: Plugin | None = None
+    trusted: bool = True
+    disabled: bool = False
+    error: str = ""
+    # the plugin's resolved settings: manifest defaults overlaid by the
+    # ``[plugins.<name>]`` policy table. The same dict the instance was built
+    # with; the bus reads it for the declarative-hook ``FROID_LOOP_SETTING_*`` env.
+    settings: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def name(self) -> str:
+        return self.manifest.name
+
+
+# re-exported by manifest.py for parser convenience
+__all__ = [
+    "API_VERSION",
+    "SUPPORTED_API",
+    "SETTING_TYPES",
+    "WORKFLOW_STAGES",
+    "WORKFLOW_ROLES",
+    "PLUGIN_SOURCES",
+    "PluginError",
+    "HookSpec",
+    "SettingSpec",
+    "WorkflowSpec",
+    "PythonSpec",
+    "PluginManifest",
+    "Plugin",
+    "LoadedPlugin",
+]

froid_loop/plugins/registry.py

@@ -0,0 +1,245 @@
+"""PluginRegistry: the inter-pillar contract.
+
+The registry collapses discovery + trust + in-process resolution into one
+read-only object the rest of the system consumes:
+
+  * the settings pillar reads ``settings_schema()``;
+  * the hook bus reads ``hooks_for(stage)``;
+  * custom orchestration reads ``provided_workflows()``.
+
+Neither consumer reaches into loader internals. Building the registry is the
+single place trust is enforced and failure is isolated:
+
+  * a plugin with no ``[python]`` loads as a data-only/declarative LoadedPlugin
+    (instance None) — its shell hooks are available to the bus;
+  * a ``[python]`` plugin is constructed only if it is in ``[plugins] enabled``
+    (``trust.require_enabled`` gates ``exec_module``); otherwise it is recorded
+    untrusted and its module is never imported;
+  * any exception while importing/constructing a trusted instance is caught
+    (``except Exception`` — never ``BaseException``, so RunStopped/SIGTERM
+    propagate), journalled, and the instance disabled. The run survives.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from dataclasses import replace
+from pathlib import Path
+
+from . import trust
+from .loader import load_plugins
+from .model import (
+    HookSpec,
+    LoadedPlugin,
+    Plugin,
+    PluginManifest,
+    SettingSpec,
+    WorkflowSpec,
+)
+
+
+def _resolve_settings(manifest: PluginManifest, policy) -> dict:
+    """Manifest defaults overlaid by the ``[plugins.<name>]`` policy table. The
+    single resolved view the instance is built with and the bus reads for env."""
+    resolved = dict(manifest.setting_defaults())
+    plugins_pol = getattr(policy, "plugins", None) if policy is not None else None
+    overrides = getattr(plugins_pol, "settings", {}).get(manifest.name, {}) if plugins_pol else {}
+    resolved.update(overrides)
+    return resolved
+
+
+def _instantiate(manifest: PluginManifest, settings: dict) -> Plugin:
+    """Import the plugin's module and construct its Plugin subclass with its
+    resolved settings.
+
+    Caller is responsible for the trust gate; this performs the actual
+    ``exec_module``. Kept tiny so the registry's try/except wraps exactly the
+    import + construct surface.
+    """
+    scripts_dir = Path(manifest.scripts_dir)
+    module_path = scripts_dir / manifest.python.module  # type: ignore[union-attr]
+    # `_parse_python` rejects an absolute, parent-climbing or root-naming module at
+    # manifest load, but lexically: a project-relative name that is a symlink out of
+    # the plugin resolves fine and would be exec'd. Re-check after resolution, since
+    # what happens below is arbitrary code execution, not a copy.
+    # Strictly below, not merely inside: `is_relative_to` is true for equal paths,
+    # so a module resolving to the plugin dir itself would pass an inside-check.
+    try:
+        resolved, base = module_path.resolve(), scripts_dir.resolve()
+        contained = resolved != base and resolved.is_relative_to(base)
+    except (OSError, RuntimeError):
+        contained = False
+    if not contained:
+        raise ImportError(f"plugin module escapes its plugin directory: {module_path}")
+    if not module_path.is_file():
+        raise FileNotFoundError(f"plugin module not found: {module_path}")
+    spec = importlib.util.spec_from_file_location(f"froid_loop_plugin_{manifest.name}", module_path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"cannot load plugin module: {module_path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    cls_name = manifest.python.cls  # type: ignore[union-attr]
+    cls = getattr(module, cls_name, None)
+    if cls is None:
+        # manifest.python is validated non-None before this loader runs (mirrors
+        # the manifest.python.cls access above).
+        raise AttributeError(
+            f"plugin module {manifest.python.module!r} has no {cls_name!r}"  # pyright: ignore[reportOptionalMemberAccess]
+        )
+    if not (isinstance(cls, type) and issubclass(cls, Plugin)):
+        raise TypeError(f"{cls_name!r} must subclass plugins.Plugin")
+    return cls(manifest, settings)
+
+
+def _resolve(manifest: PluginManifest, policy, journal) -> LoadedPlugin:
+    settings = _resolve_settings(manifest, policy)
+    if manifest.python is None:
+        if journal is not None:
+            journal.append("plugin-loaded", plugin=manifest.name, mode="declarative")
+        return LoadedPlugin(manifest=manifest, settings=settings)
+
+    if not trust.is_enabled(policy, manifest.name):
+        if journal is not None:
+            journal.append(
+                "plugin-untrusted",
+                plugin=manifest.name,
+                reason="[python] module requires [plugins] enabled",
+            )
+        return LoadedPlugin(manifest=manifest, trusted=False, settings=settings)
+
+    try:
+        instance = _instantiate(manifest, settings)
+    except Exception as e:  # isolate plugin failures; never BaseException
+        if journal is not None:
+            journal.append("plugin-error", plugin=manifest.name, error=f"{type(e).__name__}: {e}")
+        return LoadedPlugin(manifest=manifest, disabled=True, error=str(e), settings=settings)
+
+    if journal is not None:
+        journal.append("plugin-loaded", plugin=manifest.name, mode="python")
+    return LoadedPlugin(manifest=manifest, instance=instance, settings=settings)
+
+
+class PluginRegistry:
+    """Read-only view over the loaded plugins. Build once per run."""
+
+    def __init__(self, loaded: list[LoadedPlugin]):
+        # stable order: manifest priority then load (discovery/overlay) order.
+        self._loaded = sorted(loaded, key=lambda lp: lp.manifest.priority)
+
+    @classmethod
+    def build(cls, project: Path | None = None, policy=None, journal=None) -> PluginRegistry:
+        manifests = load_plugins(project, journal=journal)
+        loaded = [_resolve(m, policy, journal) for m in manifests.values()]
+        return cls(loaded)
+
+    # ----------------------------------------------------------- consumers
+
+    def plugins(self) -> list[LoadedPlugin]:
+        return list(self._loaded)
+
+    def get(self, name: str) -> LoadedPlugin | None:
+        for lp in self._loaded:
+            if lp.manifest.name == name:
+                return lp
+        return None
+
+    def hooks_for(self, stage: str) -> list[tuple[LoadedPlugin, HookSpec]]:
+        """Every (plugin, hook) bound to ``stage``, in registry order. A
+        disabled instance still contributes its *declarative* hooks (those are
+        out-of-process and independent of the in-process module that failed)."""
+        out: list[tuple[LoadedPlugin, HookSpec]] = []
+        for lp in self._loaded:
+            hook = lp.manifest.hook_for(stage)
+            if hook is not None:
+                out.append((lp, hook))
+        return out
+
+    def settings_schema(self) -> list[tuple[str, tuple[SettingSpec, ...]]]:
+        """(plugin name, setting specs) for every plugin that contributes
+        settings, in registry order. Consumed by the settings pillar."""
+        return [
+            (lp.manifest.name, lp.manifest.settings) for lp in self._loaded if lp.manifest.settings
+        ]
+
+    def provided_workflows(self) -> dict[str, tuple[str, ...]]:
+        """plugin name -> declared workflow names (for introspection / docs)."""
+        return {
+            lp.manifest.name: tuple(w.name for w in lp.manifest.workflows)
+            for lp in self._loaded
+            if lp.manifest.workflows
+        }
+
+    def workflow_stages(self) -> frozenset[str]:
+        """Every stage some loaded plugin binds a *still-enabled* workflow to. The
+        engine reads this once to precompute an O(1) injection guard — a run whose
+        plugins provide no workflows pays nothing at the per-stage check.
+
+        A workflow a setting has disabled (``<name>_enabled = false``) is dropped
+        here too, so the guard stays exact: when every step at a stage is turned
+        off the stage falls out of the set and the engine skips it entirely. This
+        mirrors the same skip in ``workflows_for`` (the settings-overlay
+        convention; see ``WorkflowSpec``)."""
+        return frozenset(
+            w.stage
+            for lp in self._loaded
+            for w in lp.manifest.workflows
+            if lp.settings.get(f"{w.name}_enabled") is not False
+        )
+
+    def workflows_for(self, stage: str) -> list[tuple[LoadedPlugin, WorkflowSpec]]:
+        """Every (plugin, workflow) injected at ``stage``, in registry order.
+
+        Only *active* plugins contribute: a data-only/declarative plugin always,
+        an in-process plugin only once enabled+constructed (instance built). An
+        un-enabled or errored ``[python]`` plugin is inert — its workflows must
+        not fire any more than its module runs (same gate as ``_active_for_seeds``).
+
+        Settings overlay: a plugin's resolved settings can tune a workflow per
+        the ``<workflow-name>_enabled`` / ``<workflow-name>_blocking`` convention
+        (see ``WorkflowSpec``). ``<name>_enabled = false`` drops the step;
+        ``<name>_blocking`` overrides the manifest's ``blocking`` flag. Absent
+        settings preserve the manifest values exactly, so a plugin that declares
+        no such settings is byte-identical to the pre-overlay behaviour."""
+        out: list[tuple[LoadedPlugin, WorkflowSpec]] = []
+        for lp in self._active_for_seeds():
+            for wf in lp.manifest.workflows_for(stage):
+                if lp.settings.get(f"{wf.name}_enabled") is False:
+                    continue  # a setting can disable a step
+                blocking = bool(lp.settings.get(f"{wf.name}_blocking", wf.blocking))
+                out.append((lp, wf if blocking == wf.blocking else replace(wf, blocking=blocking)))
+        return out
+
+    def instances(self) -> list[Plugin]:
+        """Constructed, trusted, non-disabled in-process plugins."""
+        return [lp.instance for lp in self._loaded if lp.instance is not None]
+
+    def _active_for_seeds(self) -> list[LoadedPlugin]:
+        """Plugins whose declared seeds apply: data-only/declarative plugins
+        (always active) and enabled in-process plugins (instance built). An
+        un-enabled or errored ``[python]`` plugin is inert — its module never ran,
+        so its seeds must not leak into a worktree (e.g. the Unity plugin's skill
+        tree when unity isn't enabled)."""
+        return [lp for lp in self._loaded if lp.manifest.python is None or lp.instance is not None]
+
+    def seed_files(self) -> list[str]:
+        """Union of every active plugin's ``seed_files`` (literal project-relative
+        paths), order-preserving + deduped. Consumed by worktree provisioning so a
+        plugin can prime an isolated checkout with gitignored paths it needs."""
+        return list(
+            dict.fromkeys(f for lp in self._active_for_seeds() for f in lp.manifest.seed_files)
+        )
+
+    def seed_globs(self) -> list[str]:
+        """Union of every active plugin's ``seed_globs`` (patterns expanded against
+        the main repo), order-preserving + deduped."""
+        return list(
+            dict.fromkeys(g for lp in self._active_for_seeds() for g in lp.manifest.seed_globs)
+        )
+
+    def validate(self, policy) -> None:
+        """Let every constructed in-process plugin self-validate against the run
+        policy (``Plugin.validate``). A plugin raises to reject an incompatible
+        config; the registry lets it propagate so the run fails fast at startup."""
+        for lp in self._loaded:
+            if lp.instance is not None:
+                lp.instance.validate(policy)

froid_loop/plugins/trust.py

@@ -0,0 +1,75 @@
+"""Plugin trust + api_version compatibility.
+
+Two tiers, per the design:
+
+  * Data-only / declarative plugins (no ``[python]``) carry no executable Python
+    — they load on folder-drop. Their shell hooks are the same risk surface as
+    today's ``engine.toml *_cmd`` and run through the bus like any command.
+  * A plugin that declares a ``[python]`` module is **never imported or
+    executed** unless its name is in ``policy.toml [plugins] enabled = [...]``.
+    Dropping a folder must never auto-run code — the registry calls
+    ``require_enabled`` before ``exec_module``.
+
+Compatibility is separate from trust: a manifest's ``api_version`` must be in
+the framework's ``SUPPORTED_API``. The loader decides the *consequence* of a
+mismatch (hard error for a builtin we ship, skip-with-warning for third-party).
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from .model import SUPPORTED_API, PluginError, PluginManifest
+
+
+class _HasPlugins(Protocol):
+    plugins: "_PluginsPolicyLike"
+
+
+class _PluginsPolicyLike(Protocol):
+    enabled: tuple[str, ...]
+
+
+class PluginUntrusted(PluginError):
+    """Raised when in-process Python is requested for a plugin that is not in
+    ``[plugins] enabled``. Caught by the registry, which records the instance as
+    untrusted (not constructed) rather than crashing the run."""
+
+
+def enabled_names(policy: _HasPlugins | None) -> frozenset[str]:
+    """The allowlist from ``[plugins] enabled``; empty when absent."""
+    if policy is None:
+        return frozenset()
+    plugins = getattr(policy, "plugins", None)
+    if plugins is None:
+        return frozenset()
+    return frozenset(getattr(plugins, "enabled", ()) or ())
+
+
+def is_enabled(policy: _HasPlugins | None, name: str) -> bool:
+    return name in enabled_names(policy)
+
+
+def require_enabled(policy: _HasPlugins | None, name: str) -> None:
+    """Gate in-process execution. Raises PluginUntrusted if not allowlisted."""
+    if not is_enabled(policy, name):
+        raise PluginUntrusted(
+            f"plugin {name!r} declares an in-process [python] module but is not in "
+            f"[plugins] enabled — its code will not run"
+        )
+
+
+def api_supported(api_version: int) -> bool:
+    return api_version in SUPPORTED_API
+
+
+def check_api(manifest: PluginManifest) -> str | None:
+    """Return None if the manifest's api_version is supported, else a human
+    message describing the mismatch. The loader maps this to hard-error vs skip
+    based on the manifest's source."""
+    if api_supported(manifest.api_version):
+        return None
+    return (
+        f"plugin {manifest.name!r} declares api_version {manifest.api_version}, "
+        f"unsupported by this build (supports {sorted(SUPPORTED_API)})"
+    )