katalyst-engine 2.0.0__py3-none-any.whl

katalyst_engine/core/compositional.py

@@ -0,0 +1,103 @@
+"""Grouping and namespacing — Compositionals contain other Evolvables.
+
+Models, Wings, Packages, and Snapshots are Compositionals. Members
+are stored as Identity references, not embedded objects. Resolution
+of references to live objects is handled by the model layer.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from katalyst_engine.core.evolvable import Evolvable
+from katalyst_engine.core.identity import Identity
+
+
+class MemberConstraint(BaseModel, frozen=True):
+    """Rules governing what can be a member of a Compositional.
+
+    Declares allowed kinds and cardinality bounds.
+    An empty allowed_kinds set means any kind is permitted.
+    """
+
+    allowed_kinds: frozenset[str] = frozenset()
+    """Kinds allowed as members. Empty means any kind."""
+
+    min_count: int = 0
+    """Minimum number of members required."""
+
+    max_count: int | None = None
+    """Maximum number of members allowed. None means unbounded."""
+
+
+class Compositional(Evolvable, frozen=True):
+    """An Evolvable that groups related Evolvables.
+
+    Models, Wings, Packages, Snapshots are Compositionals.
+
+    Members are stored as Identity references, not embedded objects.
+    Resolution of references to live objects is handled by the
+    model layer, not by Compositional itself.
+
+    Uses the mixin pattern: a type can be both Compositional
+    and Definitive (e.g., a Schema).
+    """
+
+    member_refs: tuple[Identity, ...] = ()
+    """Ordered references to member Evolvables."""
+
+    member_constraint: MemberConstraint = MemberConstraint()
+    """Rules governing membership."""
+
+    namespace_strategy: str = "hierarchical"
+    """How children derive their namespace. Default is hierarchical (parent FQN)."""
+
+    def has_member(self, identity: Identity) -> bool:
+        """Check if the given identity is a member of this Compositional."""
+        return identity in self.member_refs
+
+    def with_member(self, identity: Identity) -> Compositional:
+        """Return a new Compositional with the given identity added.
+
+        If the identity is already a member, returns self unchanged.
+        This is an immutable operation — a new instance is returned.
+        """
+        if identity in self.member_refs:
+            return self
+        return self.model_copy(update={"member_refs": (*self.member_refs, identity)})
+
+    def without_member(self, identity: Identity) -> Compositional:
+        """Return a new Compositional with the given identity removed.
+
+        If the identity is not a member, returns self unchanged.
+        This is an immutable operation — a new instance is returned.
+        """
+        new_refs = tuple(ref for ref in self.member_refs if ref != identity)
+        if len(new_refs) == len(self.member_refs):
+            return self
+        return self.model_copy(update={"member_refs": new_refs})
+
+    def member_count(self) -> int:
+        """Return the number of members."""
+        return len(self.member_refs)
+
+    def validate_membership(self, candidate: Evolvable) -> bool:
+        """Check if a candidate Evolvable is allowed as a member.
+
+        Validates against:
+        - allowed_kinds (if non-empty, candidate.kind must be in the set)
+        - max_count (if set, current member_count must be below it)
+
+        Does NOT check min_count (that's a post-hoc validation).
+        """
+        constraint = self.member_constraint
+
+        # Check kind constraint
+        if constraint.allowed_kinds and candidate.identity.kind not in constraint.allowed_kinds:
+            return False
+
+        # Check max cardinality
+        if constraint.max_count is not None and len(self.member_refs) >= constraint.max_count:
+            return False
+
+        return True

katalyst_engine/core/definitive.py

@@ -0,0 +1,195 @@
+"""Meta-level descriptions — Definitives define the structure of other Evolvables.
+
+Schemas, NodeDefinitions, and WingDefinitions are Definitives. A Definitive
+can describe other Definitives, making the system self-describing.
+"""
+
+from __future__ import annotations
+
+import re
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel
+
+from katalyst_engine.core.evolvable import Evolvable
+from katalyst_engine.core.lifecycle import LifecyclePolicy
+
+
+class ConstraintSeverity(str, Enum):
+    """Severity level for constraint violations."""
+
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+
+
+class Constraint(BaseModel, frozen=True):
+    """A declarative validation rule.
+
+    Describes what must be true, not how to check it.
+    Built-in kinds: "required_field", "regex", "range".
+    Unknown kinds are skipped during validation — consumers
+    handle those via custom validators.
+    """
+
+    kind: str
+    """Constraint kind: "required_field", "regex", "range", or custom."""
+
+    target: str
+    """Field or path this constraint applies to."""
+
+    rule: dict[str, Any] = {}
+    """Kind-specific rule definition (e.g. {"pattern": "^[a-z]+$"} for regex)."""
+
+    severity: ConstraintSeverity = ConstraintSeverity.ERROR
+    message: str = ""
+    """Human-readable message shown when violated."""
+
+
+class ConstraintViolation(BaseModel, frozen=True):
+    """A specific constraint that was violated during validation."""
+
+    constraint: Constraint
+    actual_value: Any = None
+    message: str = ""
+
+
+class ValidationResult(BaseModel, frozen=True):
+    """Result of validating an Evolvable against a Definitive."""
+
+    valid: bool
+    violations: tuple[ConstraintViolation, ...] = ()
+
+
+class Definitive(Evolvable, frozen=True):
+    """An Evolvable that describes the valid structure of other Evolvables.
+
+    Schemas, NodeDefinitions, WingDefinitions are Definitives.
+    A Definitive can describe other Definitives — this is what
+    makes the system self-describing.
+
+    Uses the mixin pattern: a type can be both Definitive and
+    Compositional (e.g., a Schema).
+    """
+
+    describes_kind: str
+    """The kind of Evolvable this definition governs."""
+
+    constraints: tuple[Constraint, ...] = ()
+    """Declarative validation rules for instances."""
+
+    defaults: dict[str, Any] = {}
+    """Default values applied to new instances of the described kind."""
+
+    attribute_schema: dict[str, Any] = {}
+    """Dict-based schema for spec fields (e.g. JSON Schema fragment)."""
+
+    lifecycle_policy: LifecyclePolicy | None = None
+    """If set, governs lifecycle transitions for instances."""
+
+    def validate_instance(self, instance: Evolvable) -> ValidationResult:
+        """Validate an Evolvable against this definition's constraints.
+
+        Evaluates built-in constraint kinds:
+        - "required_field": checks that labels[target] is non-empty
+        - "regex": checks that labels[target] matches rule["pattern"]
+        - "range": checks that numeric labels[target] is within rule["min"]/rule["max"]
+
+        Unknown constraint kinds are skipped (consumers handle those).
+
+        Returns a ValidationResult with all violations found.
+        """
+        violations: list[ConstraintViolation] = []
+
+        for constraint in self.constraints:
+            violation = self._evaluate_constraint(constraint, instance)
+            if violation is not None:
+                violations.append(violation)
+
+        return ValidationResult(
+            valid=len(violations) == 0,
+            violations=tuple(violations),
+        )
+
+    def is_satisfied_by(self, instance: Evolvable) -> bool:
+        """Shortcut: True if validate_instance returns valid."""
+        return self.validate_instance(instance).valid
+
+    def _evaluate_constraint(
+        self, constraint: Constraint, instance: Evolvable
+    ) -> ConstraintViolation | None:
+        """Evaluate a single constraint against an instance.
+
+        Returns a ConstraintViolation if the constraint is violated, else None.
+        Unknown constraint kinds are silently skipped (return None).
+        """
+        if constraint.kind == "required_field":
+            return self._check_required_field(constraint, instance)
+        elif constraint.kind == "regex":
+            return self._check_regex(constraint, instance)
+        elif constraint.kind == "range":
+            return self._check_range(constraint, instance)
+        # Unknown kinds are skipped — consumers handle via custom validators
+        return None
+
+    def _check_required_field(
+        self, constraint: Constraint, instance: Evolvable
+    ) -> ConstraintViolation | None:
+        """Check that a required field exists and is non-empty in labels."""
+        value = instance.labels.get(constraint.target)
+        if not value:
+            return ConstraintViolation(
+                constraint=constraint,
+                actual_value=value,
+                message=constraint.message or f"Required field '{constraint.target}' is missing",
+            )
+        return None
+
+    def _check_regex(
+        self, constraint: Constraint, instance: Evolvable
+    ) -> ConstraintViolation | None:
+        """Check that a field matches a regex pattern."""
+        pattern = constraint.rule.get("pattern", "")
+        value = instance.labels.get(constraint.target, "")
+        if not re.match(pattern, value):
+            return ConstraintViolation(
+                constraint=constraint,
+                actual_value=value,
+                message=constraint.message
+                or f"Field '{constraint.target}' does not match pattern '{pattern}'",
+            )
+        return None
+
+    def _check_range(
+        self, constraint: Constraint, instance: Evolvable
+    ) -> ConstraintViolation | None:
+        """Check that a numeric field is within a range."""
+        value_str = instance.labels.get(constraint.target, "")
+        try:
+            value = float(value_str)
+        except (ValueError, TypeError):
+            return ConstraintViolation(
+                constraint=constraint,
+                actual_value=value_str,
+                message=constraint.message or f"Field '{constraint.target}' is not a valid number",
+            )
+
+        min_val = constraint.rule.get("min")
+        max_val = constraint.rule.get("max")
+
+        if min_val is not None and value < float(min_val):
+            return ConstraintViolation(
+                constraint=constraint,
+                actual_value=value,
+                message=constraint.message
+                or f"Field '{constraint.target}' value {value} is below minimum {min_val}",
+            )
+        if max_val is not None and value > float(max_val):
+            return ConstraintViolation(
+                constraint=constraint,
+                actual_value=value,
+                message=constraint.message
+                or f"Field '{constraint.target}' value {value} is above maximum {max_val}",
+            )
+        return None

katalyst_engine/core/evolvable.py

@@ -0,0 +1,89 @@
+"""The root base model for every artifact in the engine.
+
+Evolvable is the universal supertype. Every artifact — nodes, schemas,
+definitions, relations, extensions, snapshots — is an Evolvable. It
+carries identity, version, lifecycle state, and compatibility contracts.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, computed_field
+
+from katalyst_engine.core.compatibility import CompatibilityContract
+from katalyst_engine.core.identity import Identity
+from katalyst_engine.core.lifecycle import Lifecycle
+from katalyst_engine.core.version import Version
+
+if TYPE_CHECKING:
+    from katalyst_engine.core.relation import NodeSelector
+
+
+class Evolvable(BaseModel, frozen=True):
+    """The root base model for every artifact in the engine.
+
+    Every artifact — nodes, schemas, definitions, relations,
+    extensions, snapshots — is an Evolvable. It has:
+
+    - identity: what it is (kind + name + namespace)
+    - version: which version of itself it is
+    - lifecycle: what state it's in
+    - compatibility: what guarantees it makes
+    - labels: key-value metadata for selector matching
+    - annotations: metadata not used for matching
+
+    Evolvable is immutable. Version N and version N+1 are two
+    distinct instances connected by a MigrationPath.
+    """
+
+    identity: Identity
+    version: Version = Version()
+    lifecycle: Lifecycle = Lifecycle.DRAFT
+    compatibility: CompatibilityContract = CompatibilityContract()
+    labels: dict[str, str] = {}
+    annotations: dict[str, str] = {}
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def fqn(self) -> str:
+        """Shortcut to identity.fqn."""
+        return self.identity.fqn
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def kind(self) -> str:
+        """Shortcut to identity.kind."""
+        return self.identity.kind
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def name(self) -> str:
+        """Shortcut to identity.name."""
+        return self.identity.name
+
+    def with_version(self, version: Version) -> Evolvable:
+        """Return a new Evolvable with the given version, preserving all other fields."""
+        return self.model_copy(update={"version": version})
+
+    def with_lifecycle(self, lifecycle: Lifecycle) -> Evolvable:
+        """Return a new Evolvable with the given lifecycle, preserving all other fields."""
+        return self.model_copy(update={"lifecycle": lifecycle})
+
+    def matches_selector(self, selector: NodeSelector) -> bool:
+        """Check if this Evolvable matches a NodeSelector.
+
+        Delegates to selector.matches(self) to keep matching logic
+        centralized in the selector.
+        """
+        return selector.matches(self)
+
+    def with_labels(self, **labels: str) -> Evolvable:
+        """Return a new Evolvable with additional/updated labels."""
+        merged = {**self.labels, **labels}
+        return self.model_copy(update={"labels": merged})
+
+    def with_annotations(self, **annotations: str) -> Evolvable:
+        """Return a new Evolvable with additional/updated annotations."""
+        merged: dict[str, Any] = {**self.annotations, **annotations}
+        return self.model_copy(update={"annotations": merged})

katalyst_engine/core/identity.py

@@ -0,0 +1,95 @@
+"""Identity and Fully Qualified Name (FQN) computation.
+
+Every Evolvable artifact in the engine has an Identity. The combination
+of (kind, name, namespace) is globally unique. FQN is the dot-separated
+canonical address: namespace + "." + name.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, computed_field
+
+
+class Identity(BaseModel, frozen=True):
+    """Unique identity for any artifact in the system.
+
+    Every Evolvable has an Identity. The combination of
+    (kind, name, namespace) is globally unique.
+
+    FQN (Fully Qualified Name) is computed as the dot-separated
+    path: namespace + "." + name. For root-level artifacts with
+    no namespace, FQN equals name.
+
+    Examples:
+        Identity(kind="system", name="backend", namespace="org")
+        → fqn = "org.backend"
+
+        Identity(kind="layer", name="app", namespace="org.backend.api")
+        → fqn = "org.backend.api.app"
+
+        Identity(kind="schema", name="v2alpha")
+        → fqn = "v2alpha"  (no namespace)
+    """
+
+    kind: str
+    """What type of thing this is (e.g. "node_definition", "schema", "node")."""
+
+    name: str
+    """Local name within the namespace."""
+
+    namespace: str = ""
+    """Dot-separated scoping context. Empty string means root level."""
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def fqn(self) -> str:
+        """Fully Qualified Name — dot-separated path.
+
+        Returns namespace.name if namespace is non-empty, else just name.
+        """
+        if self.namespace:
+            return f"{self.namespace}.{self.name}"
+        return self.name
+
+    def is_in_namespace(self, ns: str) -> bool:
+        """Check if this identity is within the given namespace (prefix match).
+
+        An empty namespace argument matches everything. An identity with an
+        empty namespace is only in the empty namespace.
+
+        Examples:
+            Identity(namespace="org.system").is_in_namespace("org") → True
+            Identity(namespace="org.system").is_in_namespace("other") → False
+            Identity(namespace="").is_in_namespace("") → True
+            Identity(namespace="org").is_in_namespace("") → True
+        """
+        if not ns:
+            return True
+        if not self.namespace:
+            return False
+        return self.namespace == ns or self.namespace.startswith(ns + ".")
+
+    def child(self, kind: str, name: str) -> Identity:
+        """Create a child identity nested under this one's FQN as namespace.
+
+        Example:
+            parent = Identity(kind="system", name="backend", namespace="org")
+            parent.child("stack", "api")
+            → Identity(kind="stack", name="api", namespace="org.backend")
+        """
+        return Identity(kind=kind, name=name, namespace=self.fqn)
+
+    def parent_namespace(self) -> str:
+        """Return the parent namespace (strip last segment).
+
+        Examples:
+            "org.system.stack" → "org.system"
+            "org" → ""
+            "" → ""
+        """
+        if not self.namespace:
+            return ""
+        parts = self.namespace.rsplit(".", maxsplit=1)
+        if len(parts) == 1:
+            return ""
+        return parts[0]

katalyst_engine/core/lifecycle.py

@@ -0,0 +1,62 @@
+"""Lifecycle state machine for Evolvable artifacts.
+
+Defines the lifecycle states and transition policies that govern
+how artifacts move through their life from draft to removal.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel
+
+
+class Lifecycle(str, Enum):
+    """Lifecycle state of any Evolvable artifact.
+
+    States form a directed graph of allowed transitions.
+    The default policy allows:
+        DRAFT → STABLE → DEPRECATED → REMOVED
+        DRAFT → REMOVED  (skip directly)
+    """
+
+    DRAFT = "draft"
+    STABLE = "stable"
+    DEPRECATED = "deprecated"
+    REMOVED = "removed"
+
+
+# Default allowed transitions as a module-level constant for reuse.
+DEFAULT_TRANSITIONS: tuple[tuple[Lifecycle, Lifecycle], ...] = (
+    (Lifecycle.DRAFT, Lifecycle.STABLE),
+    (Lifecycle.DRAFT, Lifecycle.REMOVED),
+    (Lifecycle.STABLE, Lifecycle.DEPRECATED),
+    (Lifecycle.DEPRECATED, Lifecycle.REMOVED),
+)
+
+
+class LifecyclePolicy(BaseModel, frozen=True):
+    """Allowed lifecycle transitions and rules.
+
+    Attached to a Definitive to govern how instances
+    of that definition can transition between states.
+
+    The default policy permits the standard progression:
+    DRAFT → STABLE → DEPRECATED → REMOVED, with a shortcut
+    from DRAFT → REMOVED.
+    """
+
+    allowed_transitions: tuple[tuple[Lifecycle, Lifecycle], ...] = DEFAULT_TRANSITIONS
+
+    require_migration_on_deprecation: bool = True
+    """If True, deprecating an artifact requires a MigrationPath to exist."""
+
+    deprecation_message_required: bool = True
+    """If True, deprecation must include a message explaining why."""
+
+    def can_transition(self, from_state: Lifecycle, to_state: Lifecycle) -> bool:
+        """Check if a transition is allowed by this policy.
+
+        Returns True if (from_state, to_state) is in the allowed_transitions list.
+        """
+        return (from_state, to_state) in self.allowed_transitions

katalyst_engine/core/relation.py

@@ -0,0 +1,151 @@
+"""Edges, selectors, and relationship claims.
+
+Relations are first-class Evolvable artifacts — typed, directed,
+versioned edges between two Evolvables. NodeSelectors enable
+pattern-based soft references that the system materializes into
+concrete Relations.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from fnmatch import fnmatch
+
+from pydantic import BaseModel
+
+from katalyst_engine.core.evolvable import Evolvable
+from katalyst_engine.core.identity import Identity
+
+
+class Cardinality(str, Enum):
+    """Cardinality of a relationship between Evolvables."""
+
+    ONE_TO_ONE = "1:1"
+    ONE_TO_MANY = "1:N"
+    MANY_TO_ONE = "N:1"
+    MANY_TO_MANY = "N:M"
+
+
+class NodeSelector(BaseModel, frozen=True):
+    """Pattern-based reference to Evolvables.
+
+    Enables soft references: a node declares relational intent
+    using selectors instead of hard names. The system materializes
+    the actual edges.
+
+    All patterns use fnmatch-style globs.
+    All criteria are ANDed — every field must match.
+
+    Examples:
+        NodeSelector(kind_pattern="layer.*")
+        → matches any Evolvable whose kind starts with "layer."
+
+        NodeSelector(label_matchers={"env": "prod"})
+        → matches any Evolvable with label env=prod
+
+        NodeSelector()  (all defaults)
+        → matches everything (universal selector)
+    """
+
+    kind_pattern: str = "*"
+    """Glob pattern for matching Evolvable.identity.kind."""
+
+    namespace_pattern: str = "*"
+    """Glob pattern for matching Evolvable.identity.namespace."""
+
+    label_matchers: dict[str, str] = {}
+    """Label key-value pairs that must all match exactly."""
+
+    name_pattern: str = "*"
+    """Glob pattern for matching Evolvable.identity.name."""
+
+    def matches(self, evolvable: Evolvable) -> bool:
+        """Check if an Evolvable matches all selector criteria.
+
+        All criteria are ANDed. A universal selector (all defaults) matches everything.
+        """
+        if not fnmatch(evolvable.identity.kind, self.kind_pattern):
+            return False
+        if not fnmatch(evolvable.identity.namespace, self.namespace_pattern):
+            return False
+        if not fnmatch(evolvable.identity.name, self.name_pattern):
+            return False
+
+        for key, value in self.label_matchers.items():
+            if evolvable.labels.get(key) != value:
+                return False
+
+        return True
+
+    def is_universal(self) -> bool:
+        """True if this selector matches everything.
+
+        A selector is universal when all patterns are "*" and
+        there are no label matchers.
+        """
+        return (
+            self.kind_pattern == "*"
+            and self.namespace_pattern == "*"
+            and self.name_pattern == "*"
+            and not self.label_matchers
+        )
+
+
+class RelationshipClaim(BaseModel, frozen=True):
+    """What a node DECLARES about its relationships.
+
+    The declaration side — what a node says about its connections
+    before the system materializes actual edges. The source_identity
+    is the node making the claim; the selector describes the target(s).
+    """
+
+    source_identity: Identity
+    """The identity of the node making this claim."""
+
+    kind: str
+    """Relationship kind, e.g. "parent", "depends_on", "extends"."""
+
+    selector: NodeSelector
+    """Pattern describing the target(s) of this relationship."""
+
+    cardinality: Cardinality = Cardinality.MANY_TO_ONE
+    """Expected cardinality of the relationship."""
+
+    optional: bool = False
+    """If True, zero matches is valid (the relationship is not required)."""
+
+    annotations: dict[str, str] = {}
+    """Additional metadata on this claim."""
+
+
+class Relation(Evolvable, frozen=True):
+    """A materialized, typed, directed edge between two Evolvables.
+
+    Relations are first-class Evolvables — they have their own
+    identity, version, lifecycle, and compatibility contract.
+
+    Relations are produced by the RelationshipMaterializer from
+    RelationshipClaims. They should not normally be constructed
+    directly by consumers.
+    """
+
+    source: Identity
+    """The identity of the source Evolvable."""
+
+    target: Identity
+    """The identity of the target Evolvable."""
+
+    relation_kind: str
+    """The type of relationship, e.g. "parent", "depends_on"."""
+
+    cardinality: Cardinality = Cardinality.MANY_TO_ONE
+    """Cardinality of this materialized relationship."""
+
+    directed: bool = True
+    """Whether this is a directed edge. Almost always True."""
+
+    materialized_from: RelationshipClaim | None = None
+    """The claim that produced this relation, if any."""
+
+    confidence: float = 1.0
+    """1.0 = exact match, <1.0 = fuzzy/inferred."""