katalyst-engine 2.0.0__py3-none-any.whl

katalyst_engine/core/version.py

@@ -0,0 +1,203 @@
+"""Semantic versioning with ranges and constraints.
+
+Immutable version objects supporting comparison, parsing, and
+semver-compatible range checking. Pre-release versions sort
+before their release counterpart: 1.0.0-alpha < 1.0.0-beta < 1.0.0.
+"""
+
+from __future__ import annotations
+
+import re
+
+from pydantic import BaseModel
+
+_VERSION_RE = re.compile(
+    r"^(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)"
+    r"(?:-(?P<pre>[a-zA-Z0-9]+(?:\.[a-zA-Z0-9]+)*))?$"
+)
+
+
+class Version(BaseModel, frozen=True):
+    """Semantic version with optional pre-release tag.
+
+    Immutable. Two versions of the same artifact are two distinct
+    Evolvable instances connected by a MigrationPath.
+
+    Supports comparison operators for sorting and range checks.
+    Pre-release versions sort before their release counterpart:
+    1.0.0-alpha < 1.0.0-beta < 1.0.0
+    """
+
+    major: int = 0
+    minor: int = 0
+    patch: int = 0
+    pre: str | None = None
+    """Pre-release tag, e.g. "alpha", "beta", "rc.1"."""
+
+    def __str__(self) -> str:
+        """Format as '1.2.3' or '1.2.3-alpha'."""
+        base = f"{self.major}.{self.minor}.{self.patch}"
+        if self.pre:
+            return f"{base}-{self.pre}"
+        return base
+
+    def _cmp_tuple(self) -> tuple[int, int, int, int, str]:
+        """Comparison tuple. Pre-release sorts before release (release = ~).
+
+        The tilde character (~) sorts after all alphanumeric strings,
+        so a release version always compares greater than any pre-release.
+        """
+        if self.pre is None:
+            return (self.major, self.minor, self.patch, 1, "")
+        return (self.major, self.minor, self.patch, 0, self.pre)
+
+    def __lt__(self, other: object) -> bool:
+        if not isinstance(other, Version):
+            return NotImplemented
+        return self._cmp_tuple() < other._cmp_tuple()
+
+    def __le__(self, other: object) -> bool:
+        if not isinstance(other, Version):
+            return NotImplemented
+        return self._cmp_tuple() <= other._cmp_tuple()
+
+    def __gt__(self, other: object) -> bool:
+        if not isinstance(other, Version):
+            return NotImplemented
+        return self._cmp_tuple() > other._cmp_tuple()
+
+    def __ge__(self, other: object) -> bool:
+        if not isinstance(other, Version):
+            return NotImplemented
+        return self._cmp_tuple() >= other._cmp_tuple()
+
+    def is_compatible_with(self, other: Version) -> bool:
+        """True if same major version (semver compatibility assumption).
+
+        Version 0.x is only compatible with itself (0.x is unstable).
+        """
+        if self.major == 0 or other.major == 0:
+            return self.major == other.major and self.minor == other.minor
+        return self.major == other.major
+
+    def next_major(self) -> Version:
+        """Return the next major version (e.g. 1.2.3 → 2.0.0)."""
+        return Version(major=self.major + 1)
+
+    def next_minor(self) -> Version:
+        """Return the next minor version (e.g. 1.2.3 → 1.3.0)."""
+        return Version(major=self.major, minor=self.minor + 1)
+
+    def next_patch(self) -> Version:
+        """Return the next patch version (e.g. 1.2.3 → 1.2.4)."""
+        return Version(major=self.major, minor=self.minor, patch=self.patch + 1)
+
+    @classmethod
+    def parse(cls, s: str) -> Version:
+        """Parse version strings like '1.2.3', '1.2.3-alpha', '0.1.0'.
+
+        Raises:
+            ValueError: If the string doesn't match the expected format.
+        """
+        m = _VERSION_RE.match(s.strip())
+        if not m:
+            raise ValueError(f"Invalid version string: {s!r}")
+        return cls(
+            major=int(m.group("major")),
+            minor=int(m.group("minor")),
+            patch=int(m.group("patch")),
+            pre=m.group("pre"),
+        )
+
+
+class VersionRange(BaseModel, frozen=True):
+    """A range constraint on versions.
+
+    Used by CanonicityClaims and dependency declarations
+    to express "I support versions >=1.0, <2.0".
+    """
+
+    min_version: Version | None = None
+    max_version: Version | None = None
+    include_min: bool = True
+    include_max: bool = False
+
+    def contains(self, v: Version) -> bool:
+        """Check if a version falls within this range."""
+        if self.min_version is not None:
+            if self.include_min:
+                if v < self.min_version:
+                    return False
+            else:
+                if v <= self.min_version:
+                    return False
+        if self.max_version is not None:
+            if self.include_max:
+                if v > self.max_version:
+                    return False
+            else:
+                if v >= self.max_version:
+                    return False
+        return True
+
+    @classmethod
+    def parse(cls, s: str) -> VersionRange:
+        """Parse version range strings.
+
+        Supported formats:
+            '*'           → unbounded (matches everything)
+            '==1.0.0'     → exact match (min=max, both inclusive)
+            '>=1.0.0'     → lower-bounded
+            '>=1.0.0,<2.0.0' → bounded range
+
+        Raises:
+            ValueError: If the string doesn't match any expected format.
+        """
+        s = s.strip()
+        if s == "*":
+            return cls()
+
+        if s.startswith("=="):
+            v = Version.parse(s[2:])
+            return cls(min_version=v, max_version=v, include_min=True, include_max=True)
+
+        parts = [p.strip() for p in s.split(",")]
+        min_v: Version | None = None
+        max_v: Version | None = None
+        inc_min = True
+        inc_max = False
+
+        for part in parts:
+            if part.startswith(">="):
+                min_v = Version.parse(part[2:])
+                inc_min = True
+            elif part.startswith(">"):
+                min_v = Version.parse(part[1:])
+                inc_min = False
+            elif part.startswith("<="):
+                max_v = Version.parse(part[2:])
+                inc_max = True
+            elif part.startswith("<"):
+                max_v = Version.parse(part[1:])
+                inc_max = False
+            else:
+                raise ValueError(f"Invalid version range component: {part!r}")
+
+        return cls(
+            min_version=min_v,
+            max_version=max_v,
+            include_min=inc_min,
+            include_max=inc_max,
+        )
+
+
+class VersionConstraint(BaseModel, frozen=True):
+    """Named version constraint for dependency declarations.
+
+    Binds a name (identifying what is constrained) to a version range.
+    """
+
+    name: str
+    """What this constrains (e.g. "api_version", "schema_version")."""
+
+    range: VersionRange

katalyst_engine/discovery/__init__.py

@@ -0,0 +1,20 @@
+"""Discovery — finding declarations from sources.
+
+.. note:: FUTURE: Wire into taxonomy when multi-source node discovery is implemented.
+   The taxonomy's filesystem discovery strategies would be refactored into a
+   FilesystemDiscoveryProtocol that returns Declaration objects. Pairs with
+   source/ and resolution/ as a coherent pipeline.
+"""
+
+from katalyst_engine.discovery.declaration import Cursor, Declaration, Format
+from katalyst_engine.discovery.dispatcher import DiscoveryDispatcher
+from katalyst_engine.discovery.protocol import DiscoveryProtocol, DiscoveryResult
+
+__all__ = [
+    "Cursor",
+    "Declaration",
+    "DiscoveryDispatcher",
+    "DiscoveryProtocol",
+    "DiscoveryResult",
+    "Format",
+]

katalyst_engine/discovery/declaration.py

@@ -0,0 +1,74 @@
+"""Declarations — raw data discovered from sources.
+
+A Declaration is the raw, unresolved data unit discovered from a source.
+It carries format metadata and a cursor for incremental discovery.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel
+
+from katalyst_engine.core.identity import Identity
+
+
+class Format(str, Enum):
+    """Serialization format of a discovered declaration."""
+
+    YAML = "yaml"
+    JSON = "json"
+    TOML = "toml"
+    MARKDOWN = "markdown"
+    BINARY = "binary"
+    UNKNOWN = "unknown"
+
+
+class Cursor(BaseModel, frozen=True):
+    """Opaque pagination/position marker for incremental discovery.
+
+    Sources use cursors to resume discovery from a previous position.
+    The engine treats cursor values as opaque — only the source
+    implementation interprets them.
+    """
+
+    value: str = ""
+    """Opaque position marker."""
+
+    source_fqn: str = ""
+    """FQN of the source this cursor belongs to."""
+
+    def is_empty(self) -> bool:
+        """True if this is a fresh/empty cursor."""
+        return self.value == ""
+
+
+class Declaration(BaseModel, frozen=True):
+    """A raw, unresolved data unit discovered from a source.
+
+    Declarations are the input to the resolution engine. They carry
+    raw spec data in whatever format the source provides, plus
+    metadata about where they came from.
+    """
+
+    identity: Identity
+    """Provisional identity assigned during discovery."""
+
+    source_fqn: str
+    """FQN of the source that produced this declaration."""
+
+    format: Format = Format.YAML
+    """Serialization format of the raw_data."""
+
+    raw_data: dict[str, Any] = {}
+    """The raw spec/content as parsed key-value data."""
+
+    raw_text: str = ""
+    """The original text content, if available."""
+
+    checksum: str = ""
+    """Content hash for change detection."""
+
+    cursor: Cursor = Cursor()
+    """Position marker for incremental discovery."""

katalyst_engine/discovery/dispatcher.py

@@ -0,0 +1,83 @@
+"""Discovery dispatcher — routes discovery to correct protocol.
+
+The dispatcher maintains a registry of DiscoveryProtocol implementations
+and routes discovery requests to the appropriate protocol based on
+source kind.
+"""
+
+from __future__ import annotations
+
+from katalyst_engine.discovery.declaration import Cursor, Declaration
+from katalyst_engine.discovery.protocol import DiscoveryProtocol, DiscoveryResult
+from katalyst_engine.source.source import Source
+
+
+class DiscoveryDispatcher:
+    """Routes discovery requests to the correct protocol implementation.
+
+    Usage:
+        dispatcher = DiscoveryDispatcher()
+        dispatcher.register(MyFilesystemProtocol())
+        result = dispatcher.discover(filesystem_source)
+    """
+
+    def __init__(self) -> None:
+        self._protocols: list[DiscoveryProtocol] = []
+
+    def register(self, protocol: DiscoveryProtocol) -> None:
+        """Register a discovery protocol implementation."""
+        self._protocols.append(protocol)
+
+    def discover(
+        self,
+        source: Source,
+        cursor: Cursor | None = None,
+    ) -> DiscoveryResult:
+        """Dispatch discovery to the first matching protocol.
+
+        Tries each registered protocol in order. The first one that
+        returns True from supports() is used.
+
+        Returns an empty result with an error if no protocol matches.
+        """
+        for protocol in self._protocols:
+            if protocol.supports(source):
+                return protocol.discover(source, cursor)
+
+        return DiscoveryResult(
+            complete=True,
+            errors=(f"No discovery protocol registered for source kind: {source.kind}",),
+        )
+
+    def discover_all(
+        self,
+        source: Source,
+    ) -> DiscoveryResult:
+        """Discover all declarations from a source (follows cursors).
+
+        Repeatedly calls discover() until complete, aggregating all
+        declarations into a single result.
+        """
+        all_declarations: list[Declaration] = []
+        all_errors: list[str] = []
+        cursor: Cursor | None = None
+
+        while True:
+            result = self.discover(source, cursor)
+            all_declarations.extend(result.declarations)
+            all_errors.extend(result.errors)
+
+            if result.complete or result.next_cursor is None:
+                break
+            cursor = result.next_cursor
+
+        return DiscoveryResult(
+            declarations=tuple(all_declarations),
+            complete=True,
+            errors=tuple(all_errors),
+        )
+
+    @property
+    def protocol_count(self) -> int:
+        """Number of registered protocols."""
+        return len(self._protocols)

katalyst_engine/discovery/protocol.py

@@ -0,0 +1,69 @@
+"""Discovery protocol — abstract interface for source adapters.
+
+Consumers implement DiscoveryProtocol to teach the engine how to
+find declarations in a specific source kind. The engine never
+does I/O directly — all I/O happens inside protocol implementations.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+from katalyst_engine.discovery.declaration import Cursor, Declaration
+from katalyst_engine.source.source import Source
+
+
+class DiscoveryProtocol(ABC):
+    """Abstract base for source discovery implementations.
+
+    Each source kind (filesystem, database, API) has its own
+    DiscoveryProtocol that knows how to enumerate declarations.
+
+    Implementations must be stateless between calls — all state
+    is carried in Cursor objects.
+    """
+
+    @abstractmethod
+    def discover(
+        self,
+        source: Source,
+        cursor: Cursor | None = None,
+    ) -> DiscoveryResult:
+        """Discover declarations from a source.
+
+        Args:
+            source: The source to discover from.
+            cursor: Resume from this position. None means start from beginning.
+
+        Returns:
+            A DiscoveryResult with declarations and an optional next cursor.
+        """
+
+    @abstractmethod
+    def supports(self, source: Source) -> bool:
+        """Check if this protocol can handle the given source."""
+
+
+@dataclass(frozen=True, slots=True)
+class DiscoveryResult:
+    """Result of a discovery pass.
+
+    Contains the declarations found and an optional cursor for
+    resuming discovery (for paginated/incremental sources).
+    """
+
+    declarations: tuple[Declaration, ...] = ()
+    next_cursor: Cursor | None = None
+    complete: bool = True
+    errors: tuple[str, ...] = ()
+
+    @property
+    def count(self) -> int:
+        """Number of declarations found."""
+        return len(self.declarations)
+
+    @property
+    def has_more(self) -> bool:
+        """True if there are more declarations to discover."""
+        return not self.complete and self.next_cursor is not None

katalyst_engine/events/__init__.py

@@ -0,0 +1,10 @@
+"""Event bus — in-process pub/sub for engine lifecycle events."""
+
+from katalyst_engine.events.bus import EventBus
+from katalyst_engine.events.event import Event, EventType
+
+__all__ = [
+    "Event",
+    "EventBus",
+    "EventType",
+]

katalyst_engine/events/bus.py

@@ -0,0 +1,102 @@
+"""In-process publish/subscribe event bus.
+
+Simple, synchronous event dispatch. Every handler sees every event
+(no type-based filtering at the bus level — handlers do their own
+filtering). One failing handler cannot break others.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from katalyst_engine.events.event import Event, EventType
+
+
+class EventBus:
+    """Synchronous pub/sub event bus.
+
+    Handlers are called in subscription order. Exceptions in handlers
+    are caught and collected — they never propagate to the publisher.
+
+    Usage:
+        bus = EventBus()
+        unsub = bus.subscribe(my_handler)
+        bus.publish(Event(type=EventType.NODE_CREATED, properties={"name": "app"}))
+        unsub()  # stop receiving events
+    """
+
+    def __init__(self) -> None:
+        self._handlers: list[Callable[[Event], Any]] = []
+        self._type_handlers: dict[EventType, list[Callable[[Event], Any]]] = {}
+        self._errors: list[tuple[Event, Exception]] = []
+
+    def subscribe(
+        self,
+        handler: Callable[[Event], Any],
+        event_type: EventType | None = None,
+    ) -> Callable[[], None]:
+        """Register a handler. Returns an unsubscribe callable.
+
+        Args:
+            handler: Callable that receives an Event. Return value is ignored.
+            event_type: If provided, the handler only receives events of this type.
+                        If None, the handler receives ALL events.
+
+        Returns:
+            A zero-argument callable that removes this handler.
+        """
+        if event_type is not None:
+            if event_type not in self._type_handlers:
+                self._type_handlers[event_type] = []
+            self._type_handlers[event_type].append(handler)
+
+            def _unsub_typed() -> None:
+                handlers = self._type_handlers.get(event_type)  # type: ignore[arg-type]
+                if handlers and handler in handlers:
+                    handlers.remove(handler)
+
+            return _unsub_typed
+
+        self._handlers.append(handler)
+
+        def _unsub() -> None:
+            if handler in self._handlers:
+                self._handlers.remove(handler)
+
+        return _unsub
+
+    def publish(self, event: Event) -> None:
+        """Dispatch an event to all matching handlers.
+
+        Global handlers (subscribed without event_type) are called first,
+        then type-specific handlers. Exceptions are caught and stored in
+        the errors list.
+        """
+        for handler in list(self._handlers):
+            try:
+                handler(event)
+            except Exception as exc:
+                self._errors.append((event, exc))
+
+        type_handlers = self._type_handlers.get(event.type, [])
+        for handler in list(type_handlers):
+            try:
+                handler(event)
+            except Exception as exc:
+                self._errors.append((event, exc))
+
+    @property
+    def errors(self) -> list[tuple[Event, Exception]]:
+        """Events that caused handler exceptions, in order."""
+        return list(self._errors)
+
+    def clear_errors(self) -> None:
+        """Clear the error log."""
+        self._errors.clear()
+
+    @property
+    def handler_count(self) -> int:
+        """Total number of registered handlers (global + typed)."""
+        typed_count = sum(len(h) for h in self._type_handlers.values())
+        return len(self._handlers) + typed_count

katalyst_engine/events/event.py

@@ -0,0 +1,82 @@
+"""Event types and event data model.
+
+Defines the vocabulary of events the engine can emit. Events are
+simple immutable data carriers — the bus handles dispatch.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class EventType(str, Enum):
+    """Categories of events the engine can emit.
+
+    Organized by subsystem. Consumers can subscribe to specific
+    types or use pattern matching on the string value.
+    """
+
+    # Lifecycle
+    ENGINE_STARTED = "engine.started"
+    ENGINE_STOPPED = "engine.stopped"
+
+    # Source management
+    SOURCE_REGISTERED = "source.registered"
+    SOURCE_REMOVED = "source.removed"
+    SOURCE_SYNC_STARTED = "source.sync.started"
+    SOURCE_SYNC_COMPLETED = "source.sync.completed"
+    SOURCE_SYNC_FAILED = "source.sync.failed"
+
+    # Discovery
+    DISCOVERY_STARTED = "discovery.started"
+    DISCOVERY_COMPLETED = "discovery.completed"
+    DECLARATION_FOUND = "discovery.declaration.found"
+
+    # Schema
+    SCHEMA_REGISTERED = "schema.registered"
+    SCHEMA_UPDATED = "schema.updated"
+    SCHEMA_DEPRECATED = "schema.deprecated"
+
+    # Model
+    NODE_CREATED = "model.node.created"
+    NODE_UPDATED = "model.node.updated"
+    NODE_DELETED = "model.node.deleted"
+    RELATION_CREATED = "model.relation.created"
+    RELATION_DELETED = "model.relation.deleted"
+
+    # Resolution
+    CONFLICT_DETECTED = "resolution.conflict.detected"
+    CONFLICT_RESOLVED = "resolution.conflict.resolved"
+
+    # Snapshot
+    SNAPSHOT_CREATED = "snapshot.created"
+    SNAPSHOT_RESTORED = "snapshot.restored"
+
+    # Extension
+    EXTENSION_REGISTERED = "extension.registered"
+    EXTENSION_TRIGGERED = "extension.triggered"
+
+    # Validation
+    VALIDATION_PASSED = "validation.passed"
+    VALIDATION_FAILED = "validation.failed"
+
+
+class Event(BaseModel, frozen=True):
+    """An immutable event emitted by the engine.
+
+    Events carry a type discriminator and a free-form properties
+    dict. The engine never inspects properties — consumers use
+    them to carry context.
+    """
+
+    type: EventType
+    """What happened."""
+
+    properties: dict[str, Any] = {}
+    """Context-specific data about the event."""
+
+    source: str = ""
+    """Optional identifier of the subsystem that emitted this event."""

katalyst_engine/extensions/__init__.py

@@ -0,0 +1,32 @@
+"""Extensions — capabilities, providers, effectors, triggers, and discovery.
+
+.. note:: WIRING IN PROGRESS: Taxonomy's plugins/ package is a near-1:1 duplicate.
+   PluginRegistry should compose ExtensionRegistry. PluginManifest maps to
+   Extension. Trigger/Effector would formalize ad-hoc event handling.
+   See ARCHITECTURE_CLEANUP.md Part 2.
+"""
+
+from katalyst_engine.extensions.capability import Capability, Extension
+from katalyst_engine.extensions.discovery import (
+    DiscoveredExtension,
+    ExtensionDiscovery,
+    ExtensionSourceKind,
+)
+from katalyst_engine.extensions.effector import Effector, EffectResult
+from katalyst_engine.extensions.provider import Provider
+from katalyst_engine.extensions.registry import ExtensionRegistry
+from katalyst_engine.extensions.trigger import Trigger, TriggerContext
+
+__all__ = [
+    "Capability",
+    "DiscoveredExtension",
+    "EffectResult",
+    "Effector",
+    "Extension",
+    "ExtensionDiscovery",
+    "ExtensionRegistry",
+    "ExtensionSourceKind",
+    "Provider",
+    "Trigger",
+    "TriggerContext",
+]