katalyst-engine 2.0.0__py3-none-any.whl

katalyst_engine/resolution/conflict.py

@@ -0,0 +1,91 @@
+"""Conflict detection models for multi-source declaration resolution.
+
+When multiple sources declare the same identity, a Conflict captures
+the competing declarations and their severity. A ConflictReport
+aggregates all conflicts from a resolution pass.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, computed_field
+
+from katalyst_engine.core.identity import Identity
+from katalyst_engine.discovery.declaration import Declaration
+
+
+class ConflictSeverity(str, Enum):
+    """How serious a conflict between declarations is.
+
+    INFO: cosmetic differences only (e.g. whitespace, ordering).
+    WARNING: non-critical field differences that may be auto-merged.
+    ERROR: contradictory values that require explicit resolution.
+    """
+
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+class Conflict(BaseModel, frozen=True):
+    """A detected conflict between declarations from different sources.
+
+    Two or more sources have provided declarations for the same identity.
+    The conflict captures which declarations disagree and which fields
+    are in contention.
+    """
+
+    identity: Identity
+    """The identity that multiple sources declare."""
+
+    declarations: tuple[Declaration, ...]
+    """The competing declarations, ordered by source priority (highest first)."""
+
+    severity: ConflictSeverity = ConflictSeverity.ERROR
+    """How serious this conflict is."""
+
+    conflicting_fields: frozenset[str] = frozenset()
+    """Field names where the declarations disagree."""
+
+    message: str = ""
+    """Human-readable description of the conflict."""
+
+
+class ConflictReport(BaseModel, frozen=True):
+    """Aggregation of all conflicts from a resolution pass.
+
+    Provides summary counts by severity and lookup by identity.
+    """
+
+    conflicts: tuple[Conflict, ...] = ()
+    """All detected conflicts."""
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def error_count(self) -> int:
+        """Number of ERROR-severity conflicts."""
+        return sum(1 for c in self.conflicts if c.severity == ConflictSeverity.ERROR)
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def warning_count(self) -> int:
+        """Number of WARNING-severity conflicts."""
+        return sum(1 for c in self.conflicts if c.severity == ConflictSeverity.WARNING)
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def total(self) -> int:
+        """Total number of conflicts."""
+        return len(self.conflicts)
+
+    def has_errors(self) -> bool:
+        """True if any ERROR-severity conflicts exist."""
+        return self.error_count > 0
+
+    def for_identity(self, identity: Identity) -> Conflict | None:
+        """Look up the conflict for a specific identity, if any."""
+        for conflict in self.conflicts:
+            if conflict.identity == identity:
+                return conflict
+        return None

katalyst_engine/resolution/engine.py

@@ -0,0 +1,131 @@
+"""Resolution engine — groups declarations, detects conflicts, applies strategies.
+
+The ResolutionEngine takes declarations from multiple sources, groups
+them by identity, detects where sources disagree, and applies resolution
+strategies in priority order to produce a single resolved declaration
+per identity.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from katalyst_engine.discovery.declaration import Declaration
+from katalyst_engine.resolution.conflict import (
+    Conflict,
+    ConflictReport,
+    ConflictSeverity,
+)
+from katalyst_engine.resolution.strategies import ResolutionStrategy
+
+
+class ResolutionResult(BaseModel, frozen=True):
+    """Output of a resolution pass.
+
+    Contains the resolved declarations (one per identity) and the
+    conflict report describing any disagreements found.
+    """
+
+    resolved: tuple[Declaration, ...] = ()
+    """One resolved declaration per identity."""
+
+    conflict_report: ConflictReport = ConflictReport()
+    """All conflicts detected, including those that were resolved."""
+
+    unresolved_identities: frozenset[str] = frozenset()
+    """FQNs of identities that could not be resolved by any strategy."""
+
+
+class ResolutionEngine:
+    """Groups declarations by identity, detects conflicts, applies strategies.
+
+    Usage:
+        engine = ResolutionEngine()
+        engine.add_strategy(CanonicalSourceStrategy(registry))
+        engine.add_strategy(MergeStrategy())
+        result = engine.resolve(declarations)
+    """
+
+    def __init__(self) -> None:
+        self._strategies: list[ResolutionStrategy] = []
+
+    def add_strategy(self, strategy: ResolutionStrategy) -> None:
+        """Add a resolution strategy. Strategies are tried in insertion order."""
+        self._strategies.append(strategy)
+
+    def resolve(self, declarations: list[Declaration]) -> ResolutionResult:
+        """Resolve a list of declarations from potentially multiple sources.
+
+        Groups declarations by identity FQN, detects conflicts where
+        multiple sources declare the same identity, and applies strategies
+        in order until one resolves each conflict.
+
+        Declarations with no conflicts pass through unchanged.
+        """
+        groups = self._group_by_identity(declarations)
+
+        resolved: list[Declaration] = []
+        conflicts: list[Conflict] = []
+        unresolved: list[str] = []
+
+        for fqn, group in groups.items():
+            if len(group) == 1:
+                resolved.append(group[0])
+                continue
+
+            conflict = self._detect_conflict(group)
+            conflicts.append(conflict)
+
+            winner = self._apply_strategies(conflict)
+            if winner is not None:
+                resolved.append(winner)
+            else:
+                unresolved.append(fqn)
+
+        return ResolutionResult(
+            resolved=tuple(resolved),
+            conflict_report=ConflictReport(conflicts=tuple(conflicts)),
+            unresolved_identities=frozenset(unresolved),
+        )
+
+    def _group_by_identity(self, declarations: list[Declaration]) -> dict[str, list[Declaration]]:
+        """Group declarations by identity FQN."""
+        groups: dict[str, list[Declaration]] = {}
+        for decl in declarations:
+            fqn = decl.identity.fqn
+            if fqn not in groups:
+                groups[fqn] = []
+            groups[fqn].append(decl)
+        return groups
+
+    def _detect_conflict(self, declarations: list[Declaration]) -> Conflict:
+        """Detect which fields conflict between declarations sharing an identity."""
+        identity = declarations[0].identity
+        all_keys: set[str] = set()
+        for decl in declarations:
+            all_keys.update(decl.raw_data.keys())
+
+        conflicting: set[str] = set()
+        for key in all_keys:
+            values = {decl.raw_data.get(key) for decl in declarations if key in decl.raw_data}
+            if len(values) > 1:
+                conflicting.add(key)
+
+        severity = ConflictSeverity.ERROR if conflicting else ConflictSeverity.WARNING
+        sources = ", ".join(d.source_fqn for d in declarations)
+
+        return Conflict(
+            identity=identity,
+            declarations=tuple(declarations),
+            severity=severity,
+            conflicting_fields=frozenset(conflicting),
+            message=f"Identity {identity.fqn} declared by multiple sources: {sources}",
+        )
+
+    def _apply_strategies(self, conflict: Conflict) -> Declaration | None:
+        """Try each strategy in order; return the first successful resolution."""
+        for strategy in self._strategies:
+            result = strategy.resolve(conflict)
+            if result is not None:
+                return result
+        return None

katalyst_engine/resolution/strategies.py

@@ -0,0 +1,122 @@
+"""Resolution strategies for choosing between conflicting declarations.
+
+Each strategy implements a different policy for picking a winner
+when multiple sources declare the same identity. Strategies are
+applied in priority order by the ResolutionEngine.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from katalyst_engine.discovery.declaration import Declaration
+from katalyst_engine.resolution.conflict import Conflict
+from katalyst_engine.source.registry import SourceRegistry
+
+
+class ResolutionStrategy(ABC):
+    """Abstract base for conflict resolution strategies.
+
+    Implementations examine a Conflict and return the winning
+    Declaration, or None if they cannot resolve it.
+    """
+
+    @abstractmethod
+    def resolve(self, conflict: Conflict) -> Declaration | None:
+        """Attempt to resolve a conflict.
+
+        Args:
+            conflict: The conflict to resolve.
+
+        Returns:
+            The winning Declaration, or None if this strategy
+            cannot resolve the conflict.
+        """
+
+
+class CanonicalSourceStrategy(ResolutionStrategy):
+    """Resolve by choosing the declaration from the highest-priority source.
+
+    Uses the SourceRegistry to look up source priorities. The declaration
+    from the source with the highest canonicity priority wins.
+    """
+
+    def __init__(self, source_registry: SourceRegistry) -> None:
+        self._registry = source_registry
+
+    def resolve(self, conflict: Conflict) -> Declaration | None:
+        """Pick the declaration from the highest-priority canonical source."""
+        best: Declaration | None = None
+        best_priority = -1
+
+        for decl in conflict.declarations:
+            source = self._registry.get_by_fqn(decl.source_fqn)
+            if source is None:
+                continue
+            priority = source.canonicity.priority
+            if priority > best_priority:
+                best = decl
+                best_priority = priority
+
+        return best
+
+
+class LatestVersionStrategy(ResolutionStrategy):
+    """Resolve by choosing the declaration with the highest version in raw_data.
+
+    Expects raw_data to contain a "version" key parseable as a semver string.
+    Falls back to string comparison if parsing fails.
+    """
+
+    def resolve(self, conflict: Conflict) -> Declaration | None:
+        """Pick the declaration with the highest version string."""
+        from katalyst_engine.core.version import Version
+
+        best: Declaration | None = None
+        best_version: Version | None = None
+
+        for decl in conflict.declarations:
+            version_str = decl.raw_data.get("version", "")
+            if not isinstance(version_str, str) or not version_str:
+                continue
+            try:
+                version = Version.parse(version_str)
+            except ValueError:
+                continue
+
+            if best_version is None or version > best_version:
+                best = decl
+                best_version = version
+
+        return best
+
+
+class MergeStrategy(ResolutionStrategy):
+    """Resolve by merging non-conflicting fields from all declarations.
+
+    If all declarations agree on every field (or a field is only set
+    by one source), produces a merged declaration. Returns None if
+    any field has genuinely conflicting values.
+    """
+
+    def resolve(self, conflict: Conflict) -> Declaration | None:
+        """Merge declarations where fields don't conflict.
+
+        Returns a merged Declaration using the first declaration as
+        the base, or None if any field values genuinely conflict.
+        """
+        if not conflict.declarations:
+            return None
+
+        merged_data: dict[str, object] = {}
+
+        for decl in conflict.declarations:
+            for key, value in decl.raw_data.items():
+                if key in merged_data:
+                    if merged_data[key] != value:
+                        return None  # genuine conflict
+                else:
+                    merged_data[key] = value
+
+        base = conflict.declarations[0]
+        return base.model_copy(update={"raw_data": merged_data})

katalyst_engine/schema/__init__.py

@@ -0,0 +1,35 @@
+"""Schema — definitions, registry, versioning, and management."""
+
+from katalyst_engine.schema.definition import (
+    FieldRef,
+    FieldSpec,
+    NodeDefinition,
+    ParentRule,
+    RelationshipDefinition,
+    SchemaDefinition,
+    WingDefinition,
+)
+from katalyst_engine.schema.manager import SchemaManager
+from katalyst_engine.schema.registry import SchemaRegistry
+from katalyst_engine.schema.versioning import (
+    SchemaVersionChange,
+    SchemaVersionComparison,
+    compare_versions,
+    plan_migration_path,
+)
+
+__all__ = [
+    "FieldRef",
+    "FieldSpec",
+    "NodeDefinition",
+    "ParentRule",
+    "RelationshipDefinition",
+    "SchemaDefinition",
+    "SchemaManager",
+    "SchemaRegistry",
+    "SchemaVersionChange",
+    "SchemaVersionComparison",
+    "WingDefinition",
+    "compare_versions",
+    "plan_migration_path",
+]

katalyst_engine/schema/definition.py

@@ -0,0 +1,281 @@
+"""Schema definitions — describe families of node types and their structure.
+
+SchemaDefinition is a Definitive that describes an entire schema family.
+NodeDefinition describes a single node kind with field specifications.
+WingDefinition describes a grouping/namespace structure.
+RelationshipDefinition describes a relationship type with classification.
+FieldRef captures a cross-reference from one field to a target kind.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+from katalyst_engine.core.definitive import Definitive
+from katalyst_engine.core.identity import Identity
+from katalyst_engine.core.relation import Cardinality
+from katalyst_engine.core.version import Version
+
+
+class FieldSpec(BaseModel, frozen=True):
+    """Specification of a single field within a NodeDefinition.
+
+    Describes the field's type, requirements, and defaults without
+    coupling to any particular serialization format.
+    """
+
+    name: str
+    """Field name as it appears in the spec dict."""
+
+    field_type: str = "string"
+    """Type hint: "string", "integer", "boolean", "list", "map", "ref"."""
+
+    required: bool = False
+    """Whether this field must be present."""
+
+    default: Any = None
+    """Default value if not provided."""
+
+    description: str = ""
+    """Human-readable description of this field."""
+
+    ref_target_kind: str = ""
+    """If field_type is 'ref', the kind of Evolvable it references."""
+
+
+class ParentRule(BaseModel, frozen=True):
+    """Declares what kinds are allowed as parents of a node kind.
+
+    Used by the SchemaRegistry to enforce parent–child relationships.
+    """
+
+    child_kind: str
+    """The kind that this rule applies to."""
+
+    allowed_parent_kinds: frozenset[str] = frozenset()
+    """Kinds allowed as parents. Empty means any kind (unconstrained)."""
+
+    required: bool = True
+    """Whether a parent is required (True) or optional (False)."""
+
+
+class FieldRef(BaseModel, frozen=True):
+    """A cross-reference from a field to a target node kind.
+
+    Captures typed relationships between node kinds that are declared
+    via fields (e.g., a ``tool`` field that references node kind ``tool``
+    with relationship type ``USES_TOOL``).
+    """
+
+    field_name: str
+    """The field on the source node that holds the reference."""
+
+    target_kind: str
+    """The node kind being referenced."""
+
+    rel_type: str = ""
+    """Optional relationship type name (e.g. "USES_TOOL", "BELONGS_TO")."""
+
+
+class NodeDefinition(Definitive, frozen=True):
+    """A Definitive describing a single node kind.
+
+    Specifies the fields that instances of this kind carry, which
+    wing they belong to, what parent rules apply, and whether this
+    kind is a root, leaf, or extension type.
+
+    This is the canonical location for all node type metadata in the
+    engine.
+    """
+
+    fields: tuple[FieldSpec, ...] = ()
+    """Ordered field specifications for this kind."""
+
+    wing: str = ""
+    """Wing this node kind belongs to (e.g. "system", "platform")."""
+
+    parent_rules: tuple[ParentRule, ...] = ()
+    """Rules governing parent relationships."""
+
+    directory_name: str = ""
+    """Conventional directory name for filesystem layout (e.g. "layers")."""
+
+    display_order: int = 0
+    """Ordering hint for UI display."""
+
+    is_root: bool = False
+    """Whether this is a root node kind (no parent required)."""
+
+    is_leaf: bool = False
+    """Whether this is a leaf node kind (no children allowed)."""
+
+    is_extension: bool = False
+    """Whether this kind extends other node kinds (like a plugin/overlay)."""
+
+    extends_kinds: tuple[str, ...] = ()
+    """If is_extension, the node kinds this extension can target."""
+
+    cross_references: tuple[FieldRef, ...] = ()
+    """Typed references from fields on this kind to other node kinds."""
+
+    scaffoldable: bool = False
+    """Whether instances of this kind support scaffolding (project generation)."""
+
+    clonable: bool = False
+    """Whether instances of this kind can be cloned."""
+
+    display_label: str = ""
+    """Human-readable singular label (e.g. "System", "Practice Area").
+    Falls back to describes_kind.replace('_', ' ').title() if empty."""
+
+    display_label_plural: str = ""
+    """Human-readable plural label (e.g. "Systems", "Practice Areas").
+    Falls back to display_label + 's' if empty."""
+
+    @property
+    def effective_display_label(self) -> str:
+        """Resolved display label, with fallback to title-cased kind."""
+        if self.display_label:
+            return self.display_label
+        return self.describes_kind.replace("_", " ").title()
+
+    @property
+    def effective_display_label_plural(self) -> str:
+        """Resolved plural display label, with fallback."""
+        if self.display_label_plural:
+            return self.display_label_plural
+        label = self.effective_display_label
+        # Simple English pluralization
+        if label.endswith("y") and not label.endswith("ey"):
+            return label[:-1] + "ies"
+        if label.endswith(("s", "sh", "ch", "x", "z")):
+            return label + "es"
+        return label + "s"
+
+    def field_by_name(self, name: str) -> FieldSpec | None:
+        """Look up a field spec by name."""
+        for field in self.fields:
+            if field.name == name:
+                return field
+        return None
+
+    def required_fields(self) -> tuple[FieldSpec, ...]:
+        """Return only the required fields."""
+        return tuple(f for f in self.fields if f.required)
+
+    @property
+    def has_parent(self) -> bool:
+        """Whether this node kind can have a parent (has any parent rules)."""
+        return len(self.parent_rules) > 0
+
+    @property
+    def allowed_parent_kinds(self) -> frozenset[str]:
+        """Union of all allowed parent kinds from all parent rules."""
+        result: set[str] = set()
+        for rule in self.parent_rules:
+            result.update(rule.allowed_parent_kinds)
+        return frozenset(result)
+
+    @property
+    def parent_required(self) -> bool:
+        """Whether any parent rule requires a parent."""
+        return any(rule.required for rule in self.parent_rules)
+
+    def cross_ref_for_field(self, field_name: str) -> FieldRef | None:
+        """Look up a cross-reference by field name."""
+        for ref in self.cross_references:
+            if ref.field_name == field_name:
+                return ref
+        return None
+
+
+class WingDefinition(Definitive, frozen=True):
+    """A Definitive describing a grouping/wing.
+
+    Wings organize node kinds into logical groups (e.g. "system" wing
+    contains systems, stacks, layers). A WingDefinition declares which
+    node kinds belong to it and their display ordering.
+    """
+
+    member_kinds: tuple[str, ...] = ()
+    """Node kinds belonging to this wing, in display order."""
+
+    display_name: str = ""
+    """Human-readable name for the wing."""
+
+    icon: str = ""
+    """Optional icon identifier for UI rendering."""
+
+
+class RelationshipDefinition(Definitive, frozen=True):
+    """A Definitive describing a relationship type.
+
+    Describes a type of relationship (edge) that can exist between
+    nodes in the taxonomy graph. Relationship definitions carry
+    classification metadata (wing, cardinality, labels) that enables
+    grouping, filtering, and display without constraining graph
+    operations.
+
+    Relationship wings are independent of node wings — they describe
+    the semantic domain of the relationship itself (e.g. "structural",
+    "capability", "verification"), not the wings of the connected nodes.
+
+    The ``describes_kind`` is the canonical snake_case identifier
+    (e.g. "provides_capability"). The graph label (SCREAMING_SNAKE_CASE)
+    is derived via the ``graph_label`` property.
+    """
+
+    description: str = ""
+    """Human-readable description of this relationship type."""
+
+    wing: str = ""
+    """Relationship wing for classification (e.g. "structural", "capability")."""
+
+    display_order: int = 0
+    """Ordering hint for UI display within a wing."""
+
+    cardinality: Cardinality = Cardinality.MANY_TO_MANY
+    """Expected cardinality of instances of this relationship type."""
+
+    directed: bool = True
+    """Whether this is a directed relationship. Almost always True."""
+
+    structural: bool = False
+    """Whether this is a structural relationship (parent, extends, depends_on, deploys_to)."""
+
+    @property
+    def graph_label(self) -> str:
+        """SCREAMING_SNAKE_CASE label for graph export.
+
+        Derived from ``describes_kind`` by upper-casing.
+
+        Examples:
+            provides_capability -> PROVIDES_CAPABILITY
+            child_of -> CHILD_OF
+            depends_on -> DEPENDS_ON
+        """
+        return self.describes_kind.upper()
+
+
+class SchemaDefinition(Definitive, frozen=True):
+    """A Definitive describing an entire schema family.
+
+    A SchemaDefinition is the top-level container that groups
+    NodeDefinitions and WingDefinitions into a coherent schema
+    version. It is itself a Definitive so it can be versioned,
+    deprecated, and migrated.
+    """
+
+    schema_version: Version = Version()
+    """The version of this schema."""
+
+    node_definitions: tuple[Identity, ...] = ()
+    """References to NodeDefinitions belonging to this schema."""
+
+    wing_definitions: tuple[Identity, ...] = ()
+    """References to WingDefinitions belonging to this schema."""
+
+    api_version: str = ""
+    """API version string (e.g. "v2alpha") for document compatibility."""