katalyst-engine 4.0.0__tar.gz → 5.0.1a1__tar.gz

{katalyst_engine-4.0.0 → katalyst_engine-5.0.1a1}/.gitignore

@@ -15,6 +15,9 @@ downloads/
 eggs/
 .eggs/
 lib/
+# Not a Python build directory: Bard's SPA keeps shared helpers (utils.ts, download.ts) in
+# src/lib, and ignoring it left a fresh clone unable to build or test the SPA.
+!plugins/bard/web/src/lib/
 lib64/
 parts/
 sdist/
@@ -95,6 +98,11 @@ Thumbs.db
 # Browser/Playwright state files
 browser-state-*.json
 
+# Agent harness scratch (run exhaust, never the design bundle)
+.opencode/sessions/
+.opencode/analysis/
+.opencode/package-lock.json
+
 # Build artifacts
 site/
 stack-tests/cucumber-report/
@@ -110,3 +118,6 @@ taxonomy/src/katalyst_taxonomy/engine/generated/
 .HANDOFF-bdd-coverage.md
 .HANDOFF-*.md
 docs/superpowers/
+
+# Node dependencies — installed, never committed
+node_modules/

{katalyst_engine-4.0.0 → katalyst_engine-5.0.1a1}/CHANGELOG.md

@@ -10,6 +10,31 @@ workspace packages. Tags use the `engine-vX.Y.Z` prefix.
 
 ---
 
+## [Unreleased]
+
+### Changed (breaking)
+
+- **`FieldSpec.field_type` must be one of `FIELD_TYPES`** (`string`, `integer`, `number`,
+  `boolean`, `list`, `map`, `ref`), exported from `katalyst_engine.schema`. Any other
+  value is refused when the field is declared; a consumer that met an unknown type could
+  only leave it unchecked. (katalyst-taxonomy#255)
+
+### Added
+
+- **`ScaffoldPolicy.variant_annotation`**: the `spec.annotations` key a kind's creation
+  template records a node's scaffold variant under (katalyst-forge's `layer`: `layerType`),
+  so a runtime reads it from the declaration instead of knowing the name.
+- **`FieldSpec.map_fields`**: for a `map` field, the keys whose types it declares
+  (`scope.layer_types` is a `list`). Declaring them on a field that is not a map is
+  refused. Taxonomy lint checks them, and `kata tax create/update --set scope.layer_types=x`
+  parses by them. (katalyst-taxonomy#254)
+
+## [4.1.0] -- 2026-06-26
+
+### Added
+
+- **`FieldSpec.allowed_values`** -- a generic, taxonomy-agnostic field-constraint mechanism. When non-empty, it declares the permitted values for a field; empty (the default `()`) means unconstrained. Consumers (e.g. the taxonomy v2 linter) project it to a JSON Schema `enum`. The engine holds only the mechanism; domain-specific values (such as the `work_item` lifecycle) live in the forge consumer, keeping the engine taxonomy-agnostic. Additive and backward-compatible. (#143, #138)
+
 ## [4.0.0] -- 2026-06-16
 
 ### Removed

{katalyst_engine-4.0.0 → katalyst_engine-5.0.1a1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: katalyst-engine
-Version: 4.0.0
+Version: 5.0.1a1
 Summary: A distributed declaration framework — primitives for schema-aware, multi-source, evolvable artifact graphs
 Project-URL: Repository, https://github.com/esimplicityinc/katalyst-taxonomy
 Author: eSimplicity
@@ -14,7 +14,9 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
+Requires-Dist: katalyst-core<1,>=0.1
 Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6
 Description-Content-Type: text/markdown
 
 # katalyst-engine

{katalyst_engine-4.0.0 → katalyst_engine-5.0.1a1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "katalyst-engine"
-version = "4.0.0"
+version = "5.0.1a1"
 description = "A distributed declaration framework — primitives for schema-aware, multi-source, evolvable artifact graphs"
 readme = "README.md"
 license = { text = "Proprietary" }
@@ -23,6 +23,10 @@ classifiers = [
 ]
 dependencies = [
     "pydantic>=2.0",
+    # LinkML is the only schema source: bundles build their definitions from the
+    # LinkML modules katalyst-core opens (toolkit/linkml.py).
+    "katalyst-core>=0.1,<1",
+    "pyyaml>=6",
 ]
 
 [project.urls]

katalyst_engine-5.0.1a1/src/katalyst_engine/__init__.py

@@ -0,0 +1,15 @@
+"""katalyst-engine — A distributed declaration framework.
+
+Primitives for schema-aware, multi-source, evolvable artifact graphs.
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _dist_version
+
+try:
+    # Generated from pyproject.toml rather than restated here. The literal this
+    # replaced read "0.1.0" — the original placeholder, carried untouched across four
+    # major releases, because nothing asserted the two agreed.
+    __version__ = _dist_version("katalyst-engine")
+except PackageNotFoundError:  # pragma: no cover - source tree without an install
+    __version__ = "0.0.0+unknown"

{katalyst_engine-4.0.0 → katalyst_engine-5.0.1a1}/src/katalyst_engine/bundle/__init__.py

@@ -11,6 +11,11 @@ from katalyst_engine.bundle.discovery import (
     DiscoveredBundle,
 )
 from katalyst_engine.bundle.loader import BundleLoader
+from katalyst_engine.bundle.policy import (
+    BundleLoadPolicy,
+    BundleVersionConflictError,
+    constraint_is_satisfied,
+)
 from katalyst_engine.bundle.protocol import (
     Bundle,
     BundleManifest,
@@ -22,9 +27,12 @@ __all__ = [
     "BUNDLE_ENTRY_POINT_GROUP",
     "Bundle",
     "BundleDiscovery",
+    "BundleLoadPolicy",
     "BundleLoader",
     "BundleManifest",
+    "BundleVersionConflictError",
     "DiscoveredBundle",
+    "constraint_is_satisfied",
     "get_creation_templates",
     "get_scaffold_templates",
 ]

{katalyst_engine-4.0.0 → katalyst_engine-5.0.1a1}/src/katalyst_engine/bundle/discovery.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 import importlib.metadata
 import logging
+from collections.abc import Callable
 from dataclasses import dataclass, field
 
 from katalyst_engine.bundle.protocol import Bundle
@@ -20,6 +21,22 @@ logger = logging.getLogger(__name__)
 BUNDLE_ENTRY_POINT_GROUP = "katalyst_engine.bundles"
 
 
+def _distribution_name(ep: importlib.metadata.EntryPoint) -> str:
+    """Distribution that registered *ep*, or ``""`` when it cannot be determined.
+
+    ``EntryPoint.dist`` is populated by ``entry_points()`` on 3.12 but is not part
+    of the type stub's guarantees and is ``None`` for a hand-built EntryPoint, so
+    this stays defensive: provenance is nice to have, never worth an exception.
+    """
+    dist = ep.dist
+    if dist is None:
+        return ""
+    try:
+        return dist.name
+    except Exception:  # noqa: BLE001 - metadata can be malformed on disk
+        return ""
+
+
 @dataclass(frozen=True, slots=True)
 class DiscoveredBundle:
     """Metadata about a discovered (but not yet loaded) bundle.
@@ -37,17 +54,40 @@ class DiscoveredBundle:
     group: str = BUNDLE_ENTRY_POINT_GROUP
     """Entry point group this was discovered from."""
 
+    distribution: str = ""
+    """Installed distribution that registered the entry point, e.g. ``katalyst-forge``.
+
+    Distinct from :attr:`name`, which is the entry-point name and is the handle
+    configuration uses to *select* a bundle. The distribution is the handle you
+    ``pip install`` or uninstall, and a report that gave only one of the two left
+    half the questions about a kind's provenance unanswerable (issue #218).
+    Empty for bundles that did not arrive over an entry point.
+    """
+
+    loader: Callable[[], Bundle] | None = None
+    """Optional pre-resolved factory, used instead of importing ``entry_point``.
+
+    Bundles that did not come from an entry point — a remote bundle
+    path-imported from the lock file, or a test double — are still describable as
+    a ``DiscoveredBundle`` this way, which is what lets *one* discovery object
+    carry every bundle a process will load (issue #218). ``entry_point`` remains
+    meaningful as provenance even when it is not the import path.
+    """
+
     def load(self) -> Bundle:
-        """Load and instantiate the bundle from its entry point.
+        """Load and instantiate the bundle.
 
-        The entry point must be a callable that returns a Bundle
-        instance. If it's a class, it will be instantiated with
-        no arguments.
+        When :attr:`loader` is set it is called and its result returned. Otherwise
+        the entry point must be a callable that returns a Bundle instance; if it's
+        a class, it will be instantiated with no arguments.
 
         Raises:
             ImportError: If the module cannot be imported.
             TypeError: If the loaded object is not a valid Bundle.
         """
+        if self.loader is not None:
+            return self.loader()
+
         module_path, _, attr_name = self.entry_point.rpartition(":")
         if not attr_name:
             # Entry point format is "module.path" (no colon)
@@ -111,6 +151,7 @@ class BundleDiscovery:
                 name=ep.name,
                 entry_point=ep.value,
                 group=self.group,
+                distribution=_distribution_name(ep),
             )
             self._discovered[ep.name] = db
             logger.debug("Discovered bundle: %s -> %s", ep.name, ep.value)
@@ -156,3 +197,13 @@ class BundleDiscovery:
         """Remove all discovered bundles and reset scan state."""
         self._discovered.clear()
         self._scanned = False
+
+    def mark_scanned(self) -> None:
+        """Declare this discovery authoritative without scanning entry points.
+
+        A caller that pre-populates a *filtered* set needs "scanned" to mean
+        "complete", not "non-empty". Without this, an explicitly empty set would
+        trigger a lazy full scan on first access and silently reintroduce every
+        bundle the filter had just removed (issue #218).
+        """
+        self._scanned = True

katalyst_engine-5.0.1a1/src/katalyst_engine/bundle/loader.py

@@ -0,0 +1,213 @@
+"""Bundle loader — discover and register all installed bundles.
+
+Provides a high-level ``load_bundles()`` function that discovers
+bundles via entry points, loads them, and registers them with
+a SchemaManager. This is the standard startup path for any
+application using the engine.
+
+Loading is governed by a :class:`~katalyst_engine.bundle.policy.BundleLoadPolicy`
+(issue #218): version constraints are checked against
+:attr:`BundleManifest.version` the moment the manifest is read, provenance is
+recorded so the registry can attribute every kind to a bundle, and
+``BundleManifest.entry_point`` is populated for bundles that arrived over an
+entry point so provenance is reportable.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+
+from katalyst_engine.bundle.discovery import BundleDiscovery, DiscoveredBundle
+from katalyst_engine.bundle.policy import BundleLoadPolicy
+from katalyst_engine.bundle.protocol import Bundle, BundleManifest
+from katalyst_engine.core.errors import EngineConfigurationError
+from katalyst_engine.schema.manager import SchemaManager
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(slots=True)
+class BundleLoader:
+    """Loads and registers bundles with a SchemaManager.
+
+    Manages the lifecycle of bundle discovery → loading → registration.
+    Tracks which bundles have been loaded and their manifests.
+
+    Usage::
+
+        loader = BundleLoader(schema_manager)
+        loader.discover_and_register()
+        # Or manually:
+        loader.register(my_bundle)
+    """
+
+    manager: SchemaManager
+    """The SchemaManager to register bundles with."""
+
+    policy: BundleLoadPolicy = field(default_factory=BundleLoadPolicy)
+    """Version constraints and conflict handling. Defaults to unconstrained."""
+
+    _loaded: dict[str, Bundle] = field(default_factory=lambda: dict[str, Bundle]())
+    _manifests: dict[str, BundleManifest] = field(
+        default_factory=lambda: dict[str, BundleManifest]()
+    )
+
+    def register(
+        self,
+        bundle: Bundle,
+        *,
+        entry_point: str = "",
+        discovered_name: str = "",
+    ) -> BundleManifest:
+        """Register a single bundle with the SchemaManager.
+
+        The version constraint is checked *before* anything is registered, so a
+        pin violation leaves the registry exactly as it was rather than
+        half-populated.
+
+        Args:
+            bundle: A Bundle instance to register.
+            entry_point: The entry point string this bundle arrived over, if any.
+                Recorded on the returned manifest — ``BundleManifest.entry_point``
+                has been declared and unpopulated since the protocol was written.
+            discovered_name: The discovery key, if different from the manifest
+                name. Consulted when matching version constraints so config may
+                name a bundle by its entry-point name.
+
+        Returns:
+            The bundle's manifest, with ``entry_point`` filled in when known.
+
+        Raises:
+            ValueError: If a bundle with the same identity is already loaded.
+            BundleVersionConflictError: If the configured version constraint is
+                not satisfied.
+            SchemaVersionMismatchError: If the bundle's LinkML modules do not carry
+                its version.
+            SchemaConflictError: If another bundle already provides one of this
+                bundle's kinds, wings, relationships or directory names.
+        """
+        manifest = bundle.manifest
+        fqn = manifest.identity.fqn
+        name = manifest.identity.name
+
+        if fqn in self._loaded:
+            raise ValueError(
+                f"Bundle already registered: {fqn!r}. "
+                f"Unregister it first or use a different identity."
+            )
+
+        self.policy.check(fqn, name, discovered_name, version=manifest.version)
+        if manifest.modules:
+            from katalyst_engine.evolution.release import bundle_release
+
+            bundle_release(bundle).check_version()
+
+        if entry_point and not manifest.entry_point:
+            manifest = manifest.model_copy(update={"entry_point": entry_point})
+
+        provider = name or discovered_name or fqn
+        with self.manager.registry.providing(provider):
+            bundle.register(self.manager)
+
+        self._loaded[fqn] = bundle
+        self._manifests[fqn] = manifest
+
+        logger.info(
+            "Registered bundle %r: %d kinds, %d wings",
+            fqn,
+            len(manifest.provided_kinds),
+            len(manifest.wing_names),
+        )
+
+        return manifest
+
+    def discover_and_register(
+        self,
+        discovery: BundleDiscovery | None = None,
+        *,
+        strict: bool | None = None,
+    ) -> list[BundleManifest]:
+        """Discover bundles via entry points and register them all.
+
+        Configuration failures — an unsatisfied version pin, two bundles
+        claiming one kind — always propagate. They are statements about what the
+        operator asked for, and logging them would turn a misconfiguration into a
+        silently reduced type system.
+
+        Args:
+            discovery: Optional pre-configured BundleDiscovery. If None, creates
+                a new one and scans entry points. Pass a pre-populated discovery
+                to load a *filtered* set — this is the seam the taxonomy layer's
+                config-aware discovery factory uses.
+            strict: Whether a bundle that fails for a non-configuration reason
+                (broken import, corrupt package) aborts the whole load. Defaults
+                to :attr:`BundleLoadPolicy.strict`.
+
+        Returns:
+            List of manifests for all successfully registered bundles.
+
+        Raises:
+            EngineConfigurationError: On any configuration failure.
+            Exception: Under ``strict``, whatever the failing bundle raised,
+                chained to a message naming it.
+        """
+        if discovery is None:
+            discovery = BundleDiscovery()
+            discovery.scan()
+
+        fail_fast = self.policy.strict if strict is None else strict
+        manifests: list[BundleManifest] = []
+
+        for discovered in discovery.all():
+            try:
+                bundle = discovered.load()
+                manifest = self.register(
+                    bundle,
+                    entry_point=discovered.entry_point,
+                    discovered_name=discovered.name,
+                )
+                manifests.append(manifest)
+            except EngineConfigurationError:
+                raise
+            except Exception as exc:
+                if fail_fast:
+                    raise RuntimeError(
+                        f"Failed to load schema bundle {discovered.name!r}: {exc}"
+                    ) from exc
+                logger.exception("Failed to load bundle %r", discovered.name)
+
+        return manifests
+
+    def register_discovered(self, discovered: DiscoveredBundle) -> BundleManifest:
+        """Load a single DiscoveredBundle and register it.
+
+        Args:
+            discovered: A discovered bundle to load and register.
+
+        Returns:
+            The bundle's manifest.
+        """
+        bundle = discovered.load()
+        return self.register(
+            bundle,
+            entry_point=discovered.entry_point,
+            discovered_name=discovered.name,
+        )
+
+    def get_manifest(self, fqn: str) -> BundleManifest | None:
+        """Look up a loaded bundle's manifest by FQN."""
+        return self._manifests.get(fqn)
+
+    def all_manifests(self) -> list[BundleManifest]:
+        """Return all loaded bundle manifests, sorted by FQN."""
+        return sorted(self._manifests.values(), key=lambda m: m.identity.fqn)
+
+    def is_loaded(self, fqn: str) -> bool:
+        """Check if a bundle with the given FQN is loaded."""
+        return fqn in self._loaded
+
+    @property
+    def loaded_count(self) -> int:
+        """Number of loaded bundles."""
+        return len(self._loaded)

{katalyst_engine-4.0.0 → katalyst_engine-5.0.1a1}/src/katalyst_engine/bundle/path_loader.py

@@ -18,10 +18,12 @@ bundle's own code executes:
 
 from __future__ import annotations
 
+import importlib
 import importlib.util
 import sys
 from dataclasses import dataclass
 from pathlib import Path
+from types import ModuleType
 
 from katalyst_engine.bundle.protocol import Bundle
 
@@ -139,6 +141,14 @@ def load_bundle_from_path(target: PathImportTarget) -> Bundle:
     module_file = target.module_file
     if not module_file.is_file():
         raise BundleLoadError(f"Bundle module file not found: {module_file}")
+    if module_file.suffix in (".yaml", ".yml"):
+        # A LinkML schema bundle: nothing to import, nothing to run.
+        from katalyst_engine.toolkit.linkml import LinkMLBundleError, LinkMLFileBundle
+
+        try:
+            return LinkMLFileBundle(module_file)
+        except LinkMLBundleError as exc:
+            raise BundleLoadError(str(exc)) from exc
 
     # Derive a stable, unique module name from the file path.
     module_name = f"_katalyst_remote_bundle_{abs(hash(str(module_file)))}"
@@ -178,3 +188,118 @@ def load_bundle_from_path(target: PathImportTarget) -> Bundle:
     finally:
         if added_to_path and str(package_root) in sys.path:
             sys.path.remove(str(package_root))
+
+
+# ---------------------------------------------------------------------------
+# Importing a package under its real name (code plugins)
+# ---------------------------------------------------------------------------
+
+
+class PackageShadowError(ValueError):
+    """A package path-imported by name would shadow one importable from elsewhere."""
+
+
+#: Top-level package name -> the identity (root + content digest) it was imported with.
+_PACKAGES: dict[str, str] = {}
+
+
+def _drop_package(package: str) -> None:
+    for name in [n for n in sys.modules if n == package or n.startswith(f"{package}.")]:
+        del sys.modules[name]
+    _PACKAGES.pop(package, None)
+
+
+def _drop_bytecode(package_dir: Path) -> None:
+    import shutil
+
+    if package_dir.is_dir():
+        for cache in package_dir.rglob("__pycache__"):
+            shutil.rmtree(cache, ignore_errors=True)
+
+
+def _importable_elsewhere(package: str, root: Path) -> str | None:
+    existing = sys.modules.get(package)
+    if existing is not None:
+        return str(getattr(existing, "__file__", None) or repr(existing))
+    try:
+        spec = importlib.util.find_spec(package)
+    except (ImportError, ValueError):
+        return None
+    if spec is None:
+        return None
+    origin = spec.origin or next(iter(spec.submodule_search_locations or ()), None)
+    if origin is None:
+        return "a namespace package"
+    try:
+        if Path(origin).resolve().is_relative_to(root.resolve()):
+            return None
+    except OSError:
+        pass
+    return origin
+
+
+def import_module_from_root(root: Path, module_path: str, *, identity: str = "") -> ModuleType:
+    """Import dotted *module_path* from *root* under its **real** name; ``sys.path`` untouched.
+
+    Unlike :func:`load_bundle_from_path`, which imports one file under a mangled name,
+    this registers the top-level package from *root* in ``sys.modules`` with
+    ``submodule_search_locations`` set, so the package's own absolute and relative
+    imports of its submodules resolve from *root*. Used for code plugins, which are
+    ordinary packages.
+
+    Args:
+        root: The directory that plays ``sys.path`` for the package.
+        module_path: ``pkg`` or ``pkg.sub.module``.
+        identity: What this import is of (root plus content digest). Importing the same
+            package with a different identity forgets the previous modules first, so a
+            changed tree is what runs.
+
+    Raises:
+        PackageShadowError: The package is importable from somewhere else (an installed
+            distribution, the standard library) — registering it would hijack it.
+        BaseException: Whatever the package's own code raises; its modules are
+            forgotten first.
+    """
+    package = module_path.split(".", 1)[0]
+    identity = identity or str(root)
+    if _PACKAGES.get(package) not in (None, identity):
+        _drop_package(package)
+        # Bytecode is validated by source mtime (whole seconds) and size, so content
+        # changed within the same second at the same size would run stale code.
+        _drop_bytecode(root / package)
+        importlib.invalidate_caches()
+    if package not in _PACKAGES:
+        elsewhere = _importable_elsewhere(package, root)
+        if elsewhere is not None:
+            raise PackageShadowError(
+                f"Package {package!r} is already importable from {elsewhere}; a package "
+                "path-imported from a source may not shadow an existing module."
+            )
+        package_dir = root / package
+        init = package_dir / "__init__.py"
+        if init.is_file():
+            spec = importlib.util.spec_from_file_location(
+                package, init, submodule_search_locations=[str(package_dir)]
+            )
+        else:
+            spec = importlib.util.spec_from_file_location(package, root / f"{package}.py")
+        if spec is None or spec.loader is None:
+            raise BundleLoadError(f"Could not create an import spec for {package!r} under {root}")
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[package] = module
+        try:
+            spec.loader.exec_module(module)
+        except BaseException:
+            _drop_package(package)
+            raise
+        _PACKAGES[package] = identity
+    try:
+        return importlib.import_module(module_path)
+    except BaseException:
+        _drop_package(package)
+        raise
+
+
+def path_imported_package(package: str) -> bool:
+    """Whether *package* was imported by :func:`import_module_from_root` in this process."""
+    return package in _PACKAGES