katalyst-engine 5.0.1a2__tar.gz → 5.0.1a4__tar.gz

{katalyst_engine-5.0.1a2 → katalyst_engine-5.0.1a4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: katalyst-engine
-Version: 5.0.1a2
+Version: 5.0.1a4
 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,7 @@ 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: katalyst-core<1,>=0.2
 Requires-Dist: pydantic>=2.0
 Requires-Dist: pyyaml>=6
 Description-Content-Type: text/markdown

{katalyst_engine-5.0.1a2 → katalyst_engine-5.0.1a4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "katalyst-engine"
-version = "5.0.1a2"
+version = "5.0.1a4"
 description = "A distributed declaration framework — primitives for schema-aware, multi-source, evolvable artifact graphs"
 readme = "README.md"
 license = { text = "Proprietary" }
@@ -25,7 +25,7 @@ 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",
+    "katalyst-core>=0.2,<1",
     "pyyaml>=6",
 ]
 

{katalyst_engine-5.0.1a2 → katalyst_engine-5.0.1a4}/src/katalyst_engine/bundle/__init__.py

@@ -13,8 +13,8 @@ from katalyst_engine.bundle.discovery import (
 from katalyst_engine.bundle.loader import BundleLoader
 from katalyst_engine.bundle.policy import (
     BundleLoadPolicy,
+    BundleRequirementError,
     BundleVersionConflictError,
-    constraint_is_satisfied,
 )
 from katalyst_engine.bundle.protocol import (
     Bundle,
@@ -30,9 +30,9 @@ __all__ = [
     "BundleLoadPolicy",
     "BundleLoader",
     "BundleManifest",
+    "BundleRequirementError",
     "BundleVersionConflictError",
     "DiscoveredBundle",
-    "constraint_is_satisfied",
     "get_creation_templates",
     "get_scaffold_templates",
 ]

{katalyst_engine-5.0.1a2 → katalyst_engine-5.0.1a4}/src/katalyst_engine/bundle/loader.py

@@ -10,7 +10,9 @@ Loading is governed by a :class:`~katalyst_engine.bundle.policy.BundleLoadPolicy
 :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.
+entry point so provenance is reportable. Once every bundle is registered, each one's
+declared ranges (:attr:`BundleManifest.requires`) are checked against katalyst-core and
+the other loaded bundles (:meth:`BundleLoader.check_requirements`).
 """
 
 from __future__ import annotations
@@ -19,9 +21,10 @@ 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.policy import BundleLoadPolicy, BundleRequirementError
 from katalyst_engine.bundle.protocol import Bundle, BundleManifest
 from katalyst_engine.core.errors import EngineConfigurationError
+from katalyst_engine.core.version import Version
 from katalyst_engine.schema.manager import SchemaManager
 
 logger = logging.getLogger(__name__)
@@ -107,6 +110,7 @@ class BundleLoader:
             manifest = manifest.model_copy(update={"entry_point": entry_point})
 
         provider = name or discovered_name or fqn
+        self._register_core_relationships()
         with self.manager.registry.providing(provider):
             bundle.register(self.manager)
 
@@ -122,6 +126,19 @@ class BundleLoader:
 
         return manifest
 
+    def _register_core_relationships(self) -> None:
+        """katalyst-core's relationship types (``child_of``), once and unattributed.
+
+        Every bundle uses them and none defines them, so they belong to no provider and
+        never conflict; a view narrowed to some bundles keeps them.
+        """
+        from katalyst_engine.toolkit.linkml import core_relationships
+
+        registry = self.manager.registry
+        for rel_def in core_relationships():
+            if registry.get_relationship(rel_def.describes_kind) is None:
+                registry.register_relationship(rel_def)
+
     def discover_and_register(
         self,
         discovery: BundleDiscovery | None = None,
@@ -177,8 +194,46 @@ class BundleLoader:
                     ) from exc
                 logger.exception("Failed to load bundle %r", discovered.name)
 
+        self.check_requirements()
         return manifests
 
+    def loaded_versions(self) -> dict[str, Version]:
+        """katalyst-core's version and each loaded bundle's, by schema name."""
+        from katalyst_engine.evolution.release import core_release
+
+        core = core_release()
+        versions = {core.name: core.version}
+        for manifest in self._manifests.values():
+            versions[manifest.identity.name] = manifest.version
+        return versions
+
+    def check_requirements(self) -> None:
+        """Refuse a loaded bundle whose declared ranges the loaded schemas don't meet.
+
+        Raises:
+            BundleRequirementError: For the first such bundle (by FQN), naming each range
+                and the loaded version.
+        """
+        from katalyst_engine.evolution.ranges import (
+            SchemaRangeError,
+            check_requirements,
+            parse_requirements,
+        )
+
+        loaded = self.loaded_versions()
+        for fqn in sorted(self._manifests):
+            manifest = self._manifests[fqn]
+            if not manifest.requires:
+                continue
+            name = manifest.identity.name
+            try:
+                ranges = parse_requirements(dict(manifest.requires), where="requires")
+            except SchemaRangeError as exc:
+                raise BundleRequirementError(name, (), detail=str(exc)) from exc
+            unsatisfied = check_requirements(ranges, loaded)
+            if unsatisfied:
+                raise BundleRequirementError(name, unsatisfied)
+
     def register_discovered(self, discovered: DiscoveredBundle) -> BundleManifest:
         """Load a single DiscoveredBundle and register it.
 

{katalyst_engine-5.0.1a2 → katalyst_engine-5.0.1a4}/src/katalyst_engine/bundle/policy.py

@@ -10,18 +10,9 @@ Deliberately in the engine and deliberately free of any notion of a profile, a
 config document or a filesystem: it is a mapping from bundle name to constraint
 plus a conflict policy, and nothing else.
 
-Constraint grammar, widest to narrowest:
-
-``*``
-    Anything.
-``^1.2.0``
-    Semver-compatible, delegated to :meth:`Version.is_compatible_with` so the
-    "0.x is only compatible with itself" rule is stated in exactly one place.
-``>=1.0.0,<2.0.0`` / ``==1.0.0`` / ``>1.0`` …
-    Delegated to :meth:`VersionRange.parse`.
-``0.1.0``
-    A bare version is an exact pin — the spelling ``spec.schemas[].version``
-    uses in the acceptance specs.
+A constraint is a schema range: the one grammar and check of
+:mod:`katalyst_engine.evolution.ranges` (``^1.2``, ``>=1.0,<2``, ``*``; a bare full version
+such as ``0.1.0`` is an exact pin, the spelling ``spec.schemas[].version`` uses).
 """
 
 from __future__ import annotations
@@ -30,13 +21,14 @@ from dataclasses import dataclass, field
 from typing import Mapping
 
 from katalyst_engine.core.errors import EngineConfigurationError
-from katalyst_engine.core.version import Version, VersionRange
+from katalyst_engine.core.version import Version
+from katalyst_engine.evolution.ranges import SchemaRange, SchemaRangeError, Unsatisfied, refusal
 from katalyst_engine.schema.conflict import ConflictPolicy
 
 __all__ = [
     "BundleLoadPolicy",
+    "BundleRequirementError",
     "BundleVersionConflictError",
-    "constraint_is_satisfied",
 ]
 
 
@@ -60,26 +52,30 @@ class BundleVersionConflictError(EngineConfigurationError):
         )
 
 
-def _empty_constraints() -> Mapping[str, str]:
-    """Typed empty-mapping factory — a bare ``lambda: {}`` is partially unknown."""
-    return {}
+class BundleRequirementError(EngineConfigurationError):
+    """A loaded bundle's declared range (:attr:`BundleManifest.requires`) is not met.
+
+    The message names the bundle, each range and the loaded version (or that the schema is
+    not loaded): ``schema bundle 'x' supports katalyst-core ^0.2, but katalyst-core 1.0.0
+    is loaded``.
+    """
 
+    def __init__(self, name: str, unsatisfied: tuple[Unsatisfied, ...], detail: str = "") -> None:
+        self.name = name
+        self.unsatisfied = unsatisfied
+        if unsatisfied:
+            message = (
+                refusal(f"schema bundle {name!r}", unsatisfied)
+                + ": install versions it supports, or a release of it that supports these"
+            )
+        else:
+            message = f"schema bundle {name!r}: {detail}"
+        super().__init__(message)
 
-def constraint_is_satisfied(constraint: str, version: Version) -> bool:
-    """Whether *version* satisfies *constraint*.
 
-    Raises:
-        ValueError: If *constraint* cannot be parsed. Callers turn this into a
-            :class:`BundleVersionConflictError` so the bundle is always named.
-    """
-    text = constraint.strip()
-    if not text or text == "*":
-        return True
-    if text.startswith("^"):
-        return version.is_compatible_with(Version.parse(text[1:]))
-    if text[0] in "<>=":
-        return VersionRange.parse(text).contains(version)
-    return version == Version.parse(text)
+def _empty_constraints() -> Mapping[str, str]:
+    """Typed empty-mapping factory — a bare ``lambda: {}`` is partially unknown."""
+    return {}
 
 
 @dataclass(frozen=True, slots=True)
@@ -135,8 +131,8 @@ class BundleLoadPolicy:
             return
         label = next((name for name in names if name), "<unnamed>")
         try:
-            satisfied = constraint_is_satisfied(constraint, version)
-        except ValueError as exc:
+            satisfied = SchemaRange.parse(constraint).contains(version)
+        except SchemaRangeError as exc:
             raise BundleVersionConflictError(
                 label, constraint, version, detail=f"unparseable constraint: {exc}"
             ) from exc

{katalyst_engine-5.0.1a2 → katalyst_engine-5.0.1a4}/src/katalyst_engine/bundle/protocol.py

@@ -19,10 +19,11 @@ Bundles may optionally declare templates:
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from pathlib import Path
 from typing import Any, Protocol, cast, runtime_checkable
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 from katalyst_engine.core.identity import Identity
 from katalyst_engine.core.version import Version
@@ -64,6 +65,12 @@ class BundleManifest(BaseModel, frozen=True):
     description: str = ""
     """Human-readable description of what this bundle provides."""
 
+    requires: Mapping[str, str] = Field(default_factory=dict[str, str])
+    """The other schemas this bundle builds on, and the versions of each it supports: a
+    schema name (``katalyst-core``, another bundle's manifest name) to a range
+    (:mod:`katalyst_engine.evolution.ranges`), e.g. ``{"katalyst-core": "^0.2"}``. The
+    loader refuses the bundle when a loaded schema is outside its range, or not loaded."""
+
     entry_point: str = ""
     """The entry point string that loaded this bundle (if discovered)."""
 

{katalyst_engine-5.0.1a2 → katalyst_engine-5.0.1a4}/src/katalyst_engine/evolution/__init__.py

@@ -7,8 +7,29 @@ its version bump and its migration.
 - :mod:`.migration`: the migration file (``migrations/<from>-to-<to>.yaml``) and the
   pure function that applies its steps to documents in memory.
 - :mod:`.gate`: the version gate CI runs (``kata core schema check``).
+- :mod:`.lock`: the versions a backend records (its schema lock), against the loaded ones.
+- :mod:`.changelog`: a release's schema changes as markdown, from the diff and the migration.
+- :mod:`.chain`: the chain of migrations from a recorded version to the loaded one, run
+  a step at a time.
+- :mod:`.ranges`: the schema ranges a dependent declares (``{name: "^9"}``), and the one
+  check that refuses it when the loaded schemas don't satisfy them.
 """
 
+from katalyst_engine.evolution.chain import (
+    ChainPlan,
+    MigrationChainError,
+    SchemaChain,
+    StepOutcome,
+    describe_step,
+    migration_chain,
+    release_migrations,
+    run_chains,
+)
+from katalyst_engine.evolution.changelog import (
+    SchemaChangelog,
+    build_changelog,
+    render_changelog,
+)
 from katalyst_engine.evolution.diff import (
     Category,
     Impact,
@@ -18,6 +39,15 @@ from katalyst_engine.evolution.diff import (
     diff_modules,
 )
 from katalyst_engine.evolution.gate import GateReport, check_release, migration_skeleton
+from katalyst_engine.evolution.lock import (
+    LOCK_FILE_NAME,
+    BundleStatus,
+    SchemaLock,
+    SchemaLockError,
+    SchemaState,
+    SchemaStatus,
+    compare_lock,
+)
 from katalyst_engine.evolution.migration import (
     CODE_HOOK_GROUP,
     Document,
@@ -28,7 +58,16 @@ from katalyst_engine.evolution.migration import (
     apply_migration,
     load_migration,
 )
+from katalyst_engine.evolution.ranges import (
+    SchemaRange,
+    SchemaRangeError,
+    Unsatisfied,
+    check_requirements,
+    parse_requirements,
+    refusal,
+)
 from katalyst_engine.evolution.release import (
+    ArchiveState,
     SchemaRelease,
     SchemaVersionMismatchError,
     bundle_release,
@@ -38,25 +77,50 @@ from katalyst_engine.evolution.release import (
 
 __all__ = [
     "CODE_HOOK_GROUP",
+    "LOCK_FILE_NAME",
+    "ArchiveState",
+    "BundleStatus",
     "Category",
+    "ChainPlan",
     "Document",
     "DocumentSet",
     "GateReport",
     "Impact",
     "Location",
     "Migration",
+    "MigrationChainError",
     "MigrationFileError",
     "MigrationStepError",
+    "SchemaChain",
     "SchemaChange",
+    "SchemaChangelog",
     "SchemaDiff",
+    "SchemaLock",
+    "SchemaLockError",
+    "SchemaRange",
+    "SchemaRangeError",
     "SchemaRelease",
+    "SchemaState",
+    "SchemaStatus",
     "SchemaVersionMismatchError",
+    "StepOutcome",
+    "Unsatisfied",
     "apply_migration",
+    "build_changelog",
     "bundle_release",
     "check_release",
+    "check_requirements",
+    "compare_lock",
     "core_release",
+    "describe_step",
     "diff_modules",
     "installed_releases",
     "load_migration",
+    "migration_chain",
     "migration_skeleton",
+    "parse_requirements",
+    "refusal",
+    "release_migrations",
+    "render_changelog",
+    "run_chains",
 ]

katalyst_engine-5.0.1a4/src/katalyst_engine/evolution/chain.py

@@ -0,0 +1,213 @@
+"""Moving documents across releases: the chain of migrations from the version a backend
+is at to the loaded one, and applying it step by step with what each step changed.
+
+A schema's migrations live beside its modules (``migrations/<from>-to-<to>.yaml``), one
+per breaking release, each from the release before it. The chain from a version is the
+migration out of its major, then the one out of the next, until the loaded major:
+8.x to 10.x runs 8 → 9, then 9 → 10. Within a major nothing is migrated.
+
+:func:`run_chains` applies the chains of several schemas to one set of documents, in
+order, a step at a time, so a dry run can say what each step did. It is pure: writing
+the result back to a backend is the caller's.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+from collections import Counter
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from katalyst_engine.core.version import Version
+from katalyst_engine.evolution.migration import (
+    CodeStep,
+    DeleteKind,
+    Document,
+    DocumentSet,
+    DropField,
+    MapEnum,
+    Migration,
+    MoveField,
+    MoveFiles,
+    RenameField,
+    RenameKind,
+    RenameRelationship,
+    Reparent,
+    SetDefault,
+    Step,
+    apply_migration,
+    load_migration,
+)
+from katalyst_engine.evolution.release import SchemaRelease
+from katalyst_engine.schema.definition import NodeDefinition
+
+__all__ = [
+    "ChainPlan",
+    "MigrationChainError",
+    "SchemaChain",
+    "StepOutcome",
+    "describe_step",
+    "migration_chain",
+    "release_migrations",
+    "run_chains",
+]
+
+
+class MigrationChainError(ValueError):
+    """No chain of migrations leads from a backend's version to the loaded one."""
+
+
+def release_migrations(release: SchemaRelease) -> tuple[Migration, ...]:
+    """Every migration a schema ships, oldest first.
+
+    Raises:
+        MigrationFileError: A migration file does not describe a migration.
+    """
+    try:
+        root = release.migrations_root
+    except Exception:  # noqa: BLE001 - a schema with no modules has no migrations
+        return ()
+    if not root.is_dir():
+        return ()
+    found = [load_migration(path) for path in sorted(root.glob("*.yaml"))]
+    return tuple(sorted(found, key=lambda m: m.source))
+
+
+def migration_chain(
+    name: str, migrations: Sequence[Migration], start: Version, target: Version
+) -> tuple[Migration, ...]:
+    """The migrations that take documents written for *start* to *target*'s major.
+
+    Raises:
+        MigrationChainError: *start* is newer than *target*, or a major has no
+            migration out of it.
+    """
+    if start.major > target.major:
+        raise MigrationChainError(
+            f"{name}: documents at {start} are newer than the loaded {target}"
+        )
+    chain: list[Migration] = []
+    current = start
+    while current.major < target.major:
+        out = [
+            m
+            for m in migrations
+            if m.source.major == current.major and current.major < m.target.major <= target.major
+        ]
+        if not out:
+            raise MigrationChainError(
+                f"{name}: no migration from {current.major}.x towards {target} "
+                f"(the schema ships {', '.join(f'{m.from_}-to-{m.to}' for m in migrations) or 'none'})"
+            )
+        if len(out) > 1:
+            listed = ", ".join(f"{m.from_}-to-{m.to}" for m in out)
+            raise MigrationChainError(f"{name}: more than one migration from {current}: {listed}")
+        chain.append(out[0])
+        current = out[0].target
+    return tuple(chain)
+
+
+def _field(kind: str | None, path: str) -> str:
+    return f"{kind}.{path}" if kind else path
+
+
+def describe_step(step: Step) -> str:
+    """One line for a step, as a dry run lists it: ``rename_field service.tags → labels``."""
+    if isinstance(step, RenameKind):
+        return f"rename_kind {step.from_} → {step.to}"
+    if isinstance(step, RenameField):
+        return f"rename_field {_field(step.kind, step.from_)} → {step.to}"
+    if isinstance(step, MoveField):
+        return f"move_field {_field(step.kind, step.from_)} → {step.to}"
+    if isinstance(step, SetDefault):
+        return f"set_default {_field(step.kind, step.field)} = {json.dumps(step.value)}"
+    if isinstance(step, DropField):
+        return f"drop_field {_field(step.kind, step.field)}"
+    if isinstance(step, DeleteKind):
+        return f"delete_kind {step.kind}"
+    if isinstance(step, MapEnum):
+        values = ", ".join(f"{k} → {v}" for k, v in step.values.items())
+        return f"map_enum {_field(step.kind, step.field)} {values}"
+    if isinstance(step, Reparent):
+        rule = (
+            f"to {step.to}"
+            if step.to is not None
+            else (f"from {step.parent_from}" if step.parent_from else f"up {step.up}")
+        )
+        return f"reparent {step.kind} {rule}"
+    if isinstance(step, MoveFiles):
+        return f"move_files {step.kind}"
+    if isinstance(step, RenameRelationship):
+        return f"rename_relationship {step.from_} → {step.to}"
+    assert isinstance(step, CodeStep)
+    return f"code {step.hook}"
+
+
+@dataclass(frozen=True)
+class SchemaChain:
+    """One schema's migrations, from the version a backend is at to the loaded one."""
+
+    name: str
+    start: Version
+    target: Version
+    migrations: tuple[Migration, ...] = ()
+
+
+@dataclass(frozen=True)
+class StepOutcome:
+    """What one step did: how many documents it wrote (new or changed) and removed."""
+
+    schema: str
+    migration: Migration
+    step: Step
+    written: int
+    removed: int
+
+    @property
+    def label(self) -> str:
+        return describe_step(self.step)
+
+
+@dataclass
+class ChainPlan:
+    """Documents after every chain, and what each step did."""
+
+    documents: DocumentSet
+    outcomes: list[StepOutcome] = field(default_factory=lambda: list[StepOutcome]())
+
+
+def _key(doc: Document) -> str:
+    return json.dumps([doc.path, doc.data], sort_keys=True, default=str)
+
+
+def run_chains(
+    chains: Sequence[SchemaChain],
+    documents: DocumentSet,
+    *,
+    nodes: Mapping[str, NodeDefinition] | None = None,
+    hooks: Mapping[str, Callable[..., Any]] | None = None,
+) -> ChainPlan:
+    """Apply each chain's migrations to *documents*, a step at a time. The input is not
+    changed.
+
+    Raises:
+        MigrationStepError: A step cannot be applied.
+    """
+    current = documents
+    outcomes: list[StepOutcome] = []
+    for chain in chains:
+        for migration in chain.migrations:
+            for step in migration.steps:
+                single = migration.model_copy(update={"steps": (step,)})
+                after = apply_migration(single, current, nodes=nodes, hooks=hooks)
+                before_keys = Counter(_key(d) for d in current.documents)
+                after_keys = Counter(_key(d) for d in after.documents)
+                written = sum((after_keys - before_keys).values())
+                removed = max(0, len(current.documents) - len(after.documents))
+                outcomes.append(StepOutcome(chain.name, migration, step, written, removed))
+                current = after
+    if current is documents:
+        current = copy.deepcopy(documents)
+    return ChainPlan(documents=current, outcomes=outcomes)