katalyst-engine 2.0.0__py3-none-any.whl

katalyst_engine/schema/manager.py

@@ -0,0 +1,95 @@
+"""Schema manager — orchestrates schema registration and validation.
+
+Coordinates the SchemaRegistry with schema definitions, providing
+a high-level interface for registering schemas, validating nodes
+against their schemas, and answering "what schema governs this kind?"
+"""
+
+from __future__ import annotations
+
+from katalyst_engine.core.definitive import ValidationResult
+from katalyst_engine.core.evolvable import Evolvable
+from katalyst_engine.schema.definition import (
+    NodeDefinition,
+    RelationshipDefinition,
+    SchemaDefinition,
+    WingDefinition,
+)
+from katalyst_engine.schema.registry import SchemaRegistry
+
+
+class SchemaManager:
+    """Orchestrator for schema registration and instance validation.
+
+    Usage:
+        manager = SchemaManager()
+        manager.register_schema(my_schema, node_defs, wing_defs, rel_defs)
+        result = manager.validate(some_node)
+        node_def = manager.definition_for_kind("layer")
+    """
+
+    def __init__(self) -> None:
+        self._registry = SchemaRegistry()
+        self._schemas: dict[str, SchemaDefinition] = {}  # keyed by api_version
+
+    @property
+    def registry(self) -> SchemaRegistry:
+        """Access the underlying SchemaRegistry."""
+        return self._registry
+
+    def register_schema(
+        self,
+        schema: SchemaDefinition,
+        node_definitions: list[NodeDefinition] | None = None,
+        wing_definitions: list[WingDefinition] | None = None,
+        relationship_definitions: list[RelationshipDefinition] | None = None,
+    ) -> None:
+        """Register a schema and its associated definitions.
+
+        Args:
+            schema: The top-level SchemaDefinition.
+            node_definitions: NodeDefinitions to register.
+            wing_definitions: WingDefinitions to register.
+            relationship_definitions: RelationshipDefinitions to register.
+
+        After registering explicit relationship definitions, calls
+        ``derive_relationships_from_nodes()`` to auto-derive stubs for
+        any cross-reference rel_types not covered by the explicit set.
+        """
+        self._schemas[schema.api_version] = schema
+
+        for node_def in node_definitions or []:
+            self._registry.register_node(node_def)
+
+        for wing_def in wing_definitions or []:
+            self._registry.register_wing(wing_def)
+
+        for rel_def in relationship_definitions or []:
+            self._registry.register_relationship(rel_def)
+
+        # Auto-derive stubs for any FieldRef.rel_type not yet registered
+        self._registry.derive_relationships_from_nodes()
+
+    def validate(self, instance: Evolvable) -> ValidationResult:
+        """Validate an Evolvable against its kind's schema definition.
+
+        Returns a passing result if no definition is registered for the kind.
+        """
+        return self._registry.validate_against_schema(instance)
+
+    def definition_for_kind(self, kind: str) -> NodeDefinition | None:
+        """Look up the NodeDefinition governing a kind."""
+        return self._registry.get_node_definition(kind)
+
+    def schema_for_api_version(self, api_version: str) -> SchemaDefinition | None:
+        """Look up a SchemaDefinition by its api_version string."""
+        return self._schemas.get(api_version)
+
+    def all_api_versions(self) -> list[str]:
+        """Return all registered api_version strings, sorted."""
+        return sorted(self._schemas.keys())
+
+    @property
+    def schema_count(self) -> int:
+        """Number of registered schemas."""
+        return len(self._schemas)

katalyst_engine/schema/registry.py

@@ -0,0 +1,367 @@
+"""Schema registry — runtime index of node definitions, wing lookups, and relationship types.
+
+Maps kind strings to NodeDefinitions, provides wing membership
+queries, enforces parent rules, and indexes relationship definitions.
+This is the single source of truth for all node type and relationship
+type metadata at runtime.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from katalyst_engine.core.definitive import ValidationResult
+from katalyst_engine.core.evolvable import Evolvable
+from katalyst_engine.schema.definition import (
+    NodeDefinition,
+    ParentRule,
+    RelationshipDefinition,
+    WingDefinition,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class SchemaRegistry:
+    """Runtime registry mapping kind strings to their definitions.
+
+    Provides fast lookups for:
+    - kind → NodeDefinition
+    - wing → member kinds
+    - kind → allowed parent kinds
+    - directory_name → kind (reverse lookup)
+    - target_kind → extension kinds
+
+    This is a mutable container populated by the SchemaManager
+    or directly by Bundle.register().
+    """
+
+    def __init__(self) -> None:
+        self._node_defs: dict[str, NodeDefinition] = {}  # keyed by describes_kind
+        self._wing_defs: dict[str, WingDefinition] = {}  # keyed by describes_kind
+        self._wing_members: dict[str, list[str]] = {}  # wing name → kinds
+        self._by_directory: dict[str, str] = {}  # directory_name → kind
+        self._extension_index: dict[str, list[str]] = {}  # target_kind → extension kinds
+        self._rel_defs: dict[str, RelationshipDefinition] = {}  # keyed by describes_kind
+        self._rel_by_wing: dict[str, list[str]] = {}  # rel wing → rel kinds
+        self._rel_by_graph_label: dict[str, str] = {}  # graph_label → describes_kind
+
+    # ── Registration ──────────────────────────────────────────────────
+
+    def register_node(self, node_def: NodeDefinition) -> None:
+        """Register a NodeDefinition, indexed by its describes_kind.
+
+        Updates all internal indexes (wing membership, directory lookup,
+        extension index). Re-registering the same kind overwrites cleanly.
+        """
+        kind = node_def.describes_kind
+        self._node_defs[kind] = node_def
+
+        # Wing membership index
+        if node_def.wing:
+            if node_def.wing not in self._wing_members:
+                self._wing_members[node_def.wing] = []
+            # Remove stale entry if re-registering
+            self._wing_members[node_def.wing] = [
+                k for k in self._wing_members[node_def.wing] if k != kind
+            ]
+            self._wing_members[node_def.wing].append(kind)
+
+        # Directory name reverse lookup
+        if node_def.directory_name:
+            self._by_directory[node_def.directory_name] = kind
+
+        # Extension index
+        if node_def.extends_kinds:
+            for target_kind in node_def.extends_kinds:
+                targets = self._extension_index.setdefault(target_kind, [])
+                if kind not in targets:
+                    targets.append(kind)
+
+    def register_wing(self, wing_def: WingDefinition) -> None:
+        """Register a WingDefinition."""
+        self._wing_defs[wing_def.describes_kind] = wing_def
+
+    def register_relationship(self, rel_def: RelationshipDefinition) -> None:
+        """Register a RelationshipDefinition, indexed by describes_kind.
+
+        Updates wing and graph_label indexes. Re-registering the same
+        kind overwrites cleanly.
+        """
+        kind = rel_def.describes_kind
+        self._rel_defs[kind] = rel_def
+
+        # Graph label reverse lookup
+        self._rel_by_graph_label[rel_def.graph_label] = kind
+
+        # Relationship wing index
+        if rel_def.wing:
+            if rel_def.wing not in self._rel_by_wing:
+                self._rel_by_wing[rel_def.wing] = []
+            # Remove stale entry if re-registering
+            self._rel_by_wing[rel_def.wing] = [
+                k for k in self._rel_by_wing[rel_def.wing] if k != kind
+            ]
+            self._rel_by_wing[rel_def.wing].append(kind)
+
+    # ── Kind lookups ──────────────────────────────────────────────────
+
+    def get_node_definition(self, kind: str) -> NodeDefinition | None:
+        """Look up the NodeDefinition for a kind."""
+        return self._node_defs.get(kind)
+
+    def require_node_definition(self, kind: str) -> NodeDefinition:
+        """Look up the NodeDefinition for a kind, raising if not found."""
+        node_def = self._node_defs.get(kind)
+        if node_def is None:
+            raise KeyError(f"Unknown node kind: {kind!r}")
+        return node_def
+
+    def __contains__(self, kind: str) -> bool:
+        """Check if a kind is registered."""
+        return kind in self._node_defs
+
+    # ── Wing lookups ──────────────────────────────────────────────────
+
+    def get_wing_definition(self, wing: str) -> WingDefinition | None:
+        """Look up a WingDefinition by its describes_kind."""
+        return self._wing_defs.get(wing)
+
+    def kinds_in_wing(self, wing: str) -> list[str]:
+        """Return all node kinds belonging to a wing, sorted by display order."""
+        kinds = self._wing_members.get(wing, [])
+        # Sort by display_order of the registered NodeDefinition
+        return sorted(
+            kinds,
+            key=lambda k: self._node_defs[k].display_order if k in self._node_defs else 0,
+        )
+
+    def all_kinds(self) -> list[str]:
+        """Return all registered node kind strings, sorted alphabetically."""
+        return sorted(self._node_defs.keys())
+
+    def sorted_kinds(self) -> list[str]:
+        """Return all kinds sorted by display order."""
+        return [
+            nd.describes_kind
+            for nd in sorted(self._node_defs.values(), key=lambda nd: nd.display_order)
+        ]
+
+    def all_wings(self) -> list[str]:
+        """Return all registered wing names (from wing_members index), sorted."""
+        return sorted(self._wing_members.keys())
+
+    # ── Type classification queries ───────────────────────────────────
+
+    def is_root(self, kind: str) -> bool:
+        """Whether this kind is a root node (no parent required)."""
+        nd = self._node_defs.get(kind)
+        return nd.is_root if nd else False
+
+    def is_leaf(self, kind: str) -> bool:
+        """Whether this kind is a leaf node (no children)."""
+        nd = self._node_defs.get(kind)
+        return nd.is_leaf if nd else False
+
+    def is_extension(self, kind: str) -> bool:
+        """Whether this kind is an extension type."""
+        nd = self._node_defs.get(kind)
+        return nd.is_extension if nd else False
+
+    def is_scaffoldable(self, kind: str) -> bool:
+        """Whether this kind supports project scaffolding."""
+        nd = self._node_defs.get(kind)
+        return nd.scaffoldable if nd else False
+
+    def is_clonable(self, kind: str) -> bool:
+        """Whether this kind can be cloned."""
+        nd = self._node_defs.get(kind)
+        return nd.clonable if nd else False
+
+    def scaffoldable_kinds(self) -> list[str]:
+        """Return all kinds that support scaffolding, sorted by display_order."""
+        return [
+            nd.describes_kind
+            for nd in sorted(self._node_defs.values(), key=lambda d: d.display_order)
+            if nd.scaffoldable
+        ]
+
+    def clonable_kinds(self) -> list[str]:
+        """Return all kinds that can be cloned, sorted by display_order."""
+        return [
+            nd.describes_kind
+            for nd in sorted(self._node_defs.values(), key=lambda d: d.display_order)
+            if nd.clonable
+        ]
+
+    def creatable_kinds(self) -> list[str]:
+        """Return all non-extension kinds that can be created, sorted by display_order."""
+        return [
+            nd.describes_kind
+            for nd in sorted(self._node_defs.values(), key=lambda d: d.display_order)
+            if not nd.is_extension
+        ]
+
+    def display_label_for(self, kind: str) -> str:
+        """Return the display label for a kind, with fallback to title-cased kind."""
+        nd = self._node_defs.get(kind)
+        if nd is not None:
+            return nd.effective_display_label
+        return kind.replace("_", " ").title()
+
+    def display_label_plural_for(self, kind: str) -> str:
+        """Return the plural display label for a kind."""
+        nd = self._node_defs.get(kind)
+        if nd is not None:
+            return nd.effective_display_label_plural
+        return kind.replace("_", " ").title() + "s"
+
+    # ── Parent / child queries ────────────────────────────────────────
+
+    def parent_rules_for(self, kind: str) -> tuple[ParentRule, ...]:
+        """Return parent rules for a node kind."""
+        node_def = self._node_defs.get(kind)
+        if node_def is None:
+            return ()
+        return node_def.parent_rules
+
+    def allowed_parent_kinds(self, kind: str) -> frozenset[str]:
+        """Return the set of kinds allowed as parents for the given kind.
+
+        Returns an empty frozenset if unconstrained or kind is unknown.
+        """
+        nd = self._node_defs.get(kind)
+        if nd is None:
+            return frozenset()
+        return nd.allowed_parent_kinds
+
+    # ── Extension queries ─────────────────────────────────────────────
+
+    def extensions_for_kind(self, target_kind: str) -> list[str]:
+        """Return extension kinds that can target the given kind."""
+        return list(self._extension_index.get(target_kind, []))
+
+    # ── Directory reverse lookup ──────────────────────────────────────
+
+    def kind_for_directory(self, directory_name: str) -> str | None:
+        """Reverse lookup: directory name → kind."""
+        return self._by_directory.get(directory_name)
+
+    # ── Validation ────────────────────────────────────────────────────
+
+    def validate_against_schema(self, instance: Evolvable) -> ValidationResult:
+        """Validate an Evolvable against its kind's NodeDefinition.
+
+        Returns a passing result if no definition is registered for the kind.
+        """
+        node_def = self._node_defs.get(instance.identity.kind)
+        if node_def is None:
+            return ValidationResult(valid=True)
+        return node_def.validate_instance(instance)
+
+    # ── Relationship lookups ──────────────────────────────────────────
+
+    def get_relationship(self, kind: str) -> RelationshipDefinition | None:
+        """Look up a RelationshipDefinition by its describes_kind."""
+        return self._rel_defs.get(kind)
+
+    def get_relationship_by_graph_label(self, label: str) -> RelationshipDefinition | None:
+        """Look up a RelationshipDefinition by its SCREAMING_SNAKE graph label."""
+        kind = self._rel_by_graph_label.get(label)
+        if kind is None:
+            return None
+        return self._rel_defs.get(kind)
+
+    def all_relationships(self) -> list[RelationshipDefinition]:
+        """Return all registered RelationshipDefinitions, sorted by display_order."""
+        return sorted(self._rel_defs.values(), key=lambda rd: rd.display_order)
+
+    def relationships_in_wing(self, wing: str) -> list[RelationshipDefinition]:
+        """Return RelationshipDefinitions in a wing, sorted by display_order."""
+        kinds = self._rel_by_wing.get(wing, [])
+        defs = [self._rel_defs[k] for k in kinds if k in self._rel_defs]
+        return sorted(defs, key=lambda rd: rd.display_order)
+
+    def relationship_wings(self) -> list[str]:
+        """Return all registered relationship wing names, sorted."""
+        return sorted(self._rel_by_wing.keys())
+
+    # ── Relationship derivation ───────────────────────────────────────
+
+    def derive_relationships_from_nodes(self) -> list[str]:
+        """Scan all registered NodeDefinitions for cross-reference rel_types.
+
+        For any FieldRef.rel_type that is not already registered as a
+        RelationshipDefinition, creates a stub definition (no wing, no
+        description) and logs a warning. Returns the list of auto-derived
+        kind strings.
+
+        This enables a "derive, don't duplicate" workflow: bundles
+        declare enriched RelationshipDefinitions for classified types,
+        and this method fills in stubs for any that were missed.
+        """
+        from katalyst_engine.core.identity import Identity
+
+        derived: list[str] = []
+        seen_rel_types: set[str] = set()
+
+        for node_def in self._node_defs.values():
+            for ref in node_def.cross_references:
+                if not ref.rel_type:
+                    continue
+                # Normalise to snake_case canonical kind
+                canonical = ref.rel_type.lower()
+                if canonical in seen_rel_types:
+                    continue
+                seen_rel_types.add(canonical)
+
+                if canonical not in self._rel_defs:
+                    stub = RelationshipDefinition(
+                        identity=Identity(
+                            kind="relationship_definition",
+                            name=canonical,
+                        ),
+                        describes_kind=canonical,
+                        description=f"Auto-derived from FieldRef.rel_type={ref.rel_type!r}",
+                    )
+                    self.register_relationship(stub)
+                    derived.append(canonical)
+                    logger.warning(
+                        "Auto-derived RelationshipDefinition for %r "
+                        "(no explicit definition registered)",
+                        canonical,
+                    )
+
+        return derived
+
+    # ── Counts / iteration ────────────────────────────────────────────
+
+    @property
+    def node_count(self) -> int:
+        """Number of registered node definitions."""
+        return len(self._node_defs)
+
+    @property
+    def wing_count(self) -> int:
+        """Number of registered wing definitions."""
+        return len(self._wing_defs)
+
+    @property
+    def relationship_count(self) -> int:
+        """Number of registered relationship definitions."""
+        return len(self._rel_defs)
+
+    def all_node_definitions(self) -> list[NodeDefinition]:
+        """Return all registered NodeDefinitions, sorted by describes_kind."""
+        return sorted(self._node_defs.values(), key=lambda nd: nd.describes_kind)
+
+    def clear(self) -> None:
+        """Remove all registered definitions."""
+        self._node_defs.clear()
+        self._wing_defs.clear()
+        self._wing_members.clear()
+        self._by_directory.clear()
+        self._extension_index.clear()
+        self._rel_defs.clear()
+        self._rel_by_wing.clear()
+        self._rel_by_graph_label.clear()

katalyst_engine/schema/versioning.py

@@ -0,0 +1,115 @@
+"""Schema versioning — comparison and migration path planning.
+
+Provides helpers for comparing schema versions and computing the
+sequence of MigrationPaths needed to move between versions.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel
+
+from katalyst_engine.core.compatibility import MigrationPath
+from katalyst_engine.core.version import Version
+
+
+class SchemaVersionChange(str, Enum):
+    """Classification of the change between two schema versions."""
+
+    NONE = "none"
+    PATCH = "patch"
+    MINOR = "minor"
+    MAJOR = "major"
+
+
+class SchemaVersionComparison(BaseModel, frozen=True):
+    """Result of comparing two schema versions.
+
+    Captures the direction and magnitude of the change, and whether
+    the versions are compatible.
+    """
+
+    from_version: Version
+    to_version: Version
+    change: SchemaVersionChange
+    compatible: bool
+    """Whether the two versions are semver-compatible."""
+
+    upgrade: bool
+    """True if to_version > from_version."""
+
+
+def compare_versions(from_v: Version, to_v: Version) -> SchemaVersionComparison:
+    """Compare two schema versions and classify the change.
+
+    Returns a SchemaVersionComparison describing the magnitude,
+    direction, and compatibility of the change.
+    """
+    if from_v == to_v:
+        change = SchemaVersionChange.NONE
+    elif from_v.major != to_v.major:
+        change = SchemaVersionChange.MAJOR
+    elif from_v.minor != to_v.minor:
+        change = SchemaVersionChange.MINOR
+    else:
+        change = SchemaVersionChange.PATCH
+
+    return SchemaVersionComparison(
+        from_version=from_v,
+        to_version=to_v,
+        change=change,
+        compatible=from_v.is_compatible_with(to_v),
+        upgrade=to_v > from_v,
+    )
+
+
+def plan_migration_path(
+    from_version: Version,
+    to_version: Version,
+    available_paths: list[MigrationPath],
+) -> list[MigrationPath]:
+    """Find an ordered sequence of migrations from one version to another.
+
+    Uses a simple BFS over available MigrationPaths. Returns an empty
+    list if no path exists.
+
+    Args:
+        from_version: Starting version.
+        to_version: Target version.
+        available_paths: All known migration paths.
+
+    Returns:
+        Ordered list of MigrationPaths from from_version to to_version,
+        or empty list if unreachable.
+    """
+    if from_version == to_version:
+        return []
+
+    adjacency: dict[str, list[MigrationPath]] = {}
+    for path in available_paths:
+        key = str(path.from_version)
+        if key not in adjacency:
+            adjacency[key] = []
+        adjacency[key].append(path)
+
+    visited: set[str] = set()
+    queue: list[list[MigrationPath]] = [[]]
+    current_versions = [str(from_version)]
+
+    while queue:
+        chain = queue.pop(0)
+        current = current_versions.pop(0)
+
+        if current in visited:
+            continue
+        visited.add(current)
+
+        for path in adjacency.get(current, []):
+            new_chain = [*chain, path]
+            if str(path.to_version) == str(to_version):
+                return new_chain
+            queue.append(new_chain)
+            current_versions.append(str(path.to_version))
+
+    return []

katalyst_engine/snapshot/__init__.py

@@ -0,0 +1,18 @@
+"""Snapshot — frozen model copies and diffing.
+
+.. note:: FUTURE: Wire into taxonomy when audit trail / change history features
+   are built. Snapshots are frozen model copies that can be diffed.
+   Current taxonomy sync uses sync_id pruning (database-native, more
+   efficient for the sync use case). Snapshots serve "show me what
+   changed between two points in time" which is a different need.
+"""
+
+from katalyst_engine.snapshot.diff import SnapshotDiff, diff_snapshots
+from katalyst_engine.snapshot.snapshot import Snapshot, SnapshotManifest
+
+__all__ = [
+    "Snapshot",
+    "SnapshotDiff",
+    "SnapshotManifest",
+    "diff_snapshots",
+]

katalyst_engine/snapshot/diff.py

@@ -0,0 +1,94 @@
+"""Snapshot diff — comparison of two snapshots.
+
+Computes the set of identities added, removed, and changed
+between two snapshots.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from katalyst_engine.core.identity import Identity
+from katalyst_engine.snapshot.snapshot import Snapshot
+
+
+class SnapshotDiff(BaseModel, frozen=True):
+    """Comparison of two snapshots showing what changed.
+
+    Captures which identities were added, removed, are present
+    in both, or have changed content (different checksums).
+    """
+
+    from_snapshot: Identity
+    """Identity of the older snapshot."""
+
+    to_snapshot: Identity
+    """Identity of the newer snapshot."""
+
+    added: frozenset[Identity] = frozenset()
+    """Identities present in the newer snapshot but not the older."""
+
+    removed: frozenset[Identity] = frozenset()
+    """Identities present in the older snapshot but not the newer."""
+
+    common: frozenset[Identity] = frozenset()
+    """Identities present in both snapshots (may have changed)."""
+
+    changed: frozenset[Identity] = frozenset()
+    """Identities whose content checksums differ between snapshots."""
+
+    @property
+    def has_changes(self) -> bool:
+        """True if any identities were added, removed, or changed."""
+        return bool(self.added) or bool(self.removed) or bool(self.changed)
+
+    @property
+    def added_count(self) -> int:
+        """Number of added identities."""
+        return len(self.added)
+
+    @property
+    def removed_count(self) -> int:
+        """Number of removed identities."""
+        return len(self.removed)
+
+    @property
+    def changed_count(self) -> int:
+        """Number of changed identities."""
+        return len(self.changed)
+
+
+def diff_snapshots(older: Snapshot, newer: Snapshot) -> SnapshotDiff:
+    """Compute the diff between two snapshots.
+
+    Args:
+        older: The baseline snapshot.
+        newer: The comparison snapshot.
+
+    Returns:
+        A SnapshotDiff describing what changed.
+    """
+    older_set = frozenset(older.member_refs)
+    newer_set = frozenset(newer.member_refs)
+
+    common = older_set & newer_set
+
+    # Compute content-changed identities when both have checksums
+    changed: frozenset[Identity] = frozenset()
+    older_checksums = older.manifest.node_checksums
+    newer_checksums = newer.manifest.node_checksums
+    if older_checksums and newer_checksums:
+        changed = frozenset(
+            ident
+            for ident in common
+            if older_checksums.get(ident.fqn) != newer_checksums.get(ident.fqn)
+        )
+
+    return SnapshotDiff(
+        from_snapshot=older.identity,
+        to_snapshot=newer.identity,
+        added=newer_set - older_set,
+        removed=older_set - newer_set,
+        common=common,
+        changed=changed,
+    )