katalyst-engine 2.0.0__py3-none-any.whl

katalyst_engine/snapshot/snapshot.py

@@ -0,0 +1,111 @@
+"""Snapshot — frozen copy of a model at a point in time.
+
+A Snapshot is a Compositional that captures the complete state of
+a model, including a timestamp and manifest of what it contains.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel
+
+from katalyst_engine.core.compositional import Compositional
+from katalyst_engine.core.identity import Identity
+
+if TYPE_CHECKING:
+    from katalyst_engine.model.node import Node
+
+
+class SnapshotManifest(BaseModel, frozen=True):
+    """Manifest describing the contents of a snapshot.
+
+    Summarizes what the snapshot contains without requiring
+    the full model to be loaded.
+    """
+
+    node_count: int = 0
+    """Number of nodes in the snapshot."""
+
+    relation_count: int = 0
+    """Number of relations in the snapshot."""
+
+    kinds: frozenset[str] = frozenset()
+    """Node kinds present in the snapshot."""
+
+    namespaces: frozenset[str] = frozenset()
+    """Namespaces present in the snapshot."""
+
+    checksum: str = ""
+    """Content hash for change detection."""
+
+    node_checksums: dict[str, str] = {}
+    """Per-node content checksums: fqn -> sha256 of spec."""
+
+
+class Snapshot(Compositional, frozen=True):
+    """Frozen copy of a model at a specific point in time.
+
+    Snapshots are Compositionals — their member_refs list the
+    identities of all nodes captured. The manifest provides
+    summary metadata.
+    """
+
+    timestamp: datetime
+    """When this snapshot was taken."""
+
+    manifest: SnapshotManifest = SnapshotManifest()
+    """Summary of snapshot contents."""
+
+    source_description: str = ""
+    """Human-readable description of what was captured."""
+
+    @classmethod
+    def create(
+        cls,
+        identity: Identity,
+        timestamp: datetime,
+        member_refs: tuple[Identity, ...],
+        manifest: SnapshotManifest | None = None,
+        nodes: tuple[Node, ...] | None = None,
+    ) -> Snapshot:
+        """Convenience factory for creating a snapshot.
+
+        Args:
+            identity: Identity for this snapshot.
+            timestamp: When the snapshot was taken.
+            member_refs: Identities of captured nodes.
+            manifest: Optional pre-computed manifest.
+            nodes: Optional Node objects for computing per-node checksums.
+
+        Returns:
+            A new Snapshot instance.
+        """
+        node_checksums: dict[str, str] = {}
+        if nodes is not None:
+            node_checksums = {
+                node.identity.fqn: hashlib.sha256(
+                    json.dumps(dict(sorted(node.spec.items())), sort_keys=True).encode()
+                ).hexdigest()
+                for node in nodes
+            }
+
+        if manifest is None:
+            kinds = frozenset(ref.kind for ref in member_refs)
+            namespaces = frozenset(ref.namespace for ref in member_refs)
+            manifest = SnapshotManifest(
+                node_count=len(member_refs),
+                kinds=kinds,
+                namespaces=namespaces,
+                node_checksums=node_checksums,
+            )
+
+        return cls(
+            identity=identity,
+            timestamp=timestamp,
+            member_refs=member_refs,
+            manifest=manifest,
+        )

katalyst_engine/source/__init__.py

@@ -0,0 +1,26 @@
+"""Source management — where data lives and what authority it claims.
+
+.. note:: FUTURE: Wire into taxonomy when multi-source node discovery is implemented.
+   The taxonomy's TaxonomyBackend abstraction maps to Source — each backend
+   (filesystem, neo4j, postgres) would register as a Source with canonicity
+   claims. Currently unused by taxonomy which has its own sources/ package
+   for template management (a different domain).
+"""
+
+from katalyst_engine.source.manifest import SourceManifest
+from katalyst_engine.source.registry import SourceRegistry
+from katalyst_engine.source.source import (
+    CanonicityClaim,
+    Source,
+    SourceHealth,
+    SourceKind,
+)
+
+__all__ = [
+    "CanonicityClaim",
+    "Source",
+    "SourceHealth",
+    "SourceKind",
+    "SourceManifest",
+    "SourceRegistry",
+]

katalyst_engine/source/manifest.py

@@ -0,0 +1,45 @@
+"""Source manifest — declares what a source provides.
+
+A SourceManifest is the metadata document a source publishes
+describing what kinds of data it contains, its schema versions,
+and last-known sync state.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel
+
+from katalyst_engine.core.identity import Identity
+from katalyst_engine.core.version import Version
+
+
+class SourceManifest(BaseModel, frozen=True):
+    """Metadata published by a source about its contents.
+
+    The manifest is used by the discovery dispatcher to decide
+    which discovery protocols to invoke and by the resolution
+    engine to understand source freshness.
+    """
+
+    source_identity: Identity
+    """Identity of the source this manifest describes."""
+
+    available_kinds: frozenset[str] = frozenset()
+    """Kinds of declarations this source can provide."""
+
+    schema_version: Version | None = None
+    """Schema version the source's data conforms to."""
+
+    last_sync: datetime | None = None
+    """When this source was last successfully synced."""
+
+    declaration_count: int | None = None
+    """Approximate number of declarations, if known."""
+
+    checksum: str = ""
+    """Content hash for change detection. Empty if unknown."""
+
+    labels: dict[str, str] = {}
+    """Additional metadata."""

katalyst_engine/source/registry.py

@@ -0,0 +1,122 @@
+"""Source registry — manages all configured sources.
+
+Central index of registered sources. Provides lookup by identity,
+kind, and canonicity queries.
+"""
+
+from __future__ import annotations
+
+from fnmatch import fnmatch
+
+from katalyst_engine.core.identity import Identity
+from katalyst_engine.source.manifest import SourceManifest
+from katalyst_engine.source.source import Source, SourceHealth
+
+
+class SourceRegistry:
+    """Registry of all configured data sources.
+
+    Sources are registered and looked up by identity. The registry
+    also provides queries for finding canonical sources for a given
+    kind of data.
+
+    This is a mutable container — sources can be added and removed
+    at runtime as the engine discovers new data locations.
+    """
+
+    def __init__(self) -> None:
+        self._sources: dict[str, Source] = {}  # keyed by fqn
+        self._manifests: dict[str, SourceManifest] = {}  # keyed by source fqn
+
+    def register(self, source: Source) -> None:
+        """Register a source. Overwrites if identity already exists."""
+        self._sources[source.identity.fqn] = source
+
+    def unregister(self, identity: Identity) -> bool:
+        """Remove a source. Returns True if it existed."""
+        fqn = identity.fqn
+        removed = fqn in self._sources
+        self._sources.pop(fqn, None)
+        self._manifests.pop(fqn, None)
+        return removed
+
+    def get(self, identity: Identity) -> Source | None:
+        """Look up a source by identity."""
+        return self._sources.get(identity.fqn)
+
+    def get_by_fqn(self, fqn: str) -> Source | None:
+        """Look up a source by FQN string."""
+        return self._sources.get(fqn)
+
+    def set_manifest(self, manifest: SourceManifest) -> None:
+        """Update the manifest for a source."""
+        self._manifests[manifest.source_identity.fqn] = manifest
+
+    def get_manifest(self, identity: Identity) -> SourceManifest | None:
+        """Get the manifest for a source."""
+        return self._manifests.get(identity.fqn)
+
+    def all_sources(self) -> list[Source]:
+        """Return all registered sources, ordered by FQN."""
+        return sorted(self._sources.values(), key=lambda s: s.identity.fqn)
+
+    def healthy_sources(self) -> list[Source]:
+        """Return sources in HEALTHY state."""
+        return [s for s in self._sources.values() if s.health == SourceHealth.HEALTHY]
+
+    def sources_for_kind(self, kind: str) -> list[Source]:
+        """Find sources that claim to provide a given kind.
+
+        Checks canonicity.kind_patterns using fnmatch glob matching.
+        Sources with no kind_patterns claim are excluded.
+        """
+        results: list[Source] = []
+        for source in self._sources.values():
+            if not source.canonicity.kind_patterns:
+                continue
+            for pattern in source.canonicity.kind_patterns:
+                if fnmatch(kind, pattern):
+                    results.append(source)
+                    break
+        return sorted(results, key=lambda s: -s.canonicity.priority)
+
+    def canonical_source_for(self, kind: str, namespace: str = "") -> Source | None:
+        """Find the highest-priority canonical source for a kind + namespace.
+
+        Returns the source with the highest canonicity priority that
+        matches both the kind and namespace patterns. Returns None if
+        no source claims canonicity.
+        """
+        best: Source | None = None
+        best_priority = -1
+
+        for source in self._sources.values():
+            claim = source.canonicity
+            if not claim.kind_patterns:
+                continue
+
+            kind_match = any(fnmatch(kind, p) for p in claim.kind_patterns)
+            if not kind_match:
+                continue
+
+            ns_match = True
+            if claim.namespace_patterns:
+                ns_match = any(fnmatch(namespace, p) for p in claim.namespace_patterns)
+            if not ns_match:
+                continue
+
+            if claim.priority > best_priority:
+                best = source
+                best_priority = claim.priority
+
+        return best
+
+    @property
+    def count(self) -> int:
+        """Number of registered sources."""
+        return len(self._sources)
+
+    def clear(self) -> None:
+        """Remove all sources and manifests."""
+        self._sources.clear()
+        self._manifests.clear()

katalyst_engine/source/source.py

@@ -0,0 +1,92 @@
+"""Source definitions — where data lives and what authority it claims.
+
+A Source is a registered location from which the engine discovers
+declarations. Each source has a kind (filesystem, database, API),
+a canonicity claim (is it authoritative?), and health state.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel
+
+from katalyst_engine.core.identity import Identity
+from katalyst_engine.core.version import VersionRange
+
+
+class SourceKind(str, Enum):
+    """Known kinds of data sources."""
+
+    FILESYSTEM = "filesystem"
+    DATABASE = "database"
+    API = "api"
+    MEMORY = "memory"
+    REGISTRY = "registry"
+
+
+class SourceHealth(str, Enum):
+    """Health state of a source."""
+
+    UNKNOWN = "unknown"
+    HEALTHY = "healthy"
+    DEGRADED = "degraded"
+    UNAVAILABLE = "unavailable"
+
+
+class CanonicityClaim(BaseModel, frozen=True):
+    """What authority a source claims over particular kinds of data.
+
+    A source that claims canonicity for kind "layer" is asserting that
+    its declarations for layers are authoritative. During conflict
+    resolution, canonical sources win over non-canonical ones.
+    """
+
+    kind_patterns: frozenset[str] = frozenset()
+    """Glob patterns for the kinds this source is canonical for. Empty = no claim."""
+
+    namespace_patterns: frozenset[str] = frozenset()
+    """Glob patterns for namespaces. Empty = all namespaces."""
+
+    version_range: VersionRange | None = None
+    """Optional version range this claim applies to."""
+
+    priority: int = 0
+    """Higher priority wins when two sources claim canonicity for the same data."""
+
+    exclusive: bool = False
+    """If True, this source is the ONLY authority. Other sources' data is ignored."""
+
+
+class Source(BaseModel, frozen=True):
+    """A registered data source in the engine.
+
+    Sources are identified by an Identity (so they are addressable
+    in the same namespace as everything else). They describe where
+    data lives, what authority it claims, and how to connect to it.
+    """
+
+    identity: Identity
+    """Unique identity of this source."""
+
+    kind: SourceKind
+    """What type of source this is."""
+
+    uri: str = ""
+    """Connection URI or path. Interpretation depends on kind."""
+
+    canonicity: CanonicityClaim = CanonicityClaim()
+    """What authority this source claims."""
+
+    health: SourceHealth = SourceHealth.UNKNOWN
+    """Current health state."""
+
+    labels: dict[str, str] = {}
+    """Metadata labels for filtering and selection."""
+
+    config: dict[str, str] = {}
+    """Source-specific configuration (credentials excluded)."""
+
+    def with_health(self, health: SourceHealth) -> Source:
+        """Return a new Source with updated health state."""
+        return self.model_copy(update={"health": health})

katalyst_engine/toolkit/__init__.py

@@ -0,0 +1,22 @@
+"""Toolkit — stateless utilities for template rendering and file operations.
+
+Provides generic helpers used by bundles, plugins, and adapters.
+No domain knowledge — these are pure utility functions.
+"""
+
+from katalyst_engine.toolkit.file_ops import (
+    copy_file,
+    copy_tree_no_overwrite,
+    copy_tree_rendered,
+    copy_tree_rendered_per_variant,
+)
+from katalyst_engine.toolkit.rendering import render_file, render_tokens
+
+__all__ = [
+    "copy_file",
+    "copy_tree_no_overwrite",
+    "copy_tree_rendered",
+    "copy_tree_rendered_per_variant",
+    "render_file",
+    "render_tokens",
+]

katalyst_engine/toolkit/file_ops.py

@@ -0,0 +1,194 @@
+"""File tree operations — copy, render, and merge directory trees.
+
+Provides generic file operations for scaffolding and template
+expansion. These functions DO perform I/O but are domain-agnostic —
+they know nothing about taxonomy, nodes, or bundles.
+"""
+
+from __future__ import annotations
+
+import shutil
+from collections.abc import Callable
+from pathlib import Path
+from typing import Mapping, Sequence
+
+from katalyst_engine.toolkit.rendering import render_tokens
+
+
+def copy_tree_rendered(
+    src: Path,
+    dest: Path,
+    context: Mapping[str, str],
+    *,
+    skip_names: frozenset[str] = frozenset(),
+    skip_root_file: str = "",
+) -> list[Path]:
+    """Copy a directory tree, rendering ``{{ key }}`` tokens in text files.
+
+    Walks the *src* directory recursively, rendering token placeholders
+    in text file contents using the provided *context*. Binary files
+    (that fail UTF-8 decoding) are copied verbatim.
+
+    Args:
+        src: Source directory to copy from.
+        dest: Destination directory to copy into.
+        context: Token replacement context for ``{{ key }}`` substitution.
+        skip_names: Set of directory names to skip at the root level.
+        skip_root_file: A single filename to skip at the root level.
+
+    Returns:
+        List of paths written to *dest*.
+    """
+    written: list[Path] = []
+
+    def _should_skip(rel: Path) -> bool:
+        if rel.parts and rel.parts[0] in skip_names:
+            return True
+        if skip_root_file and rel == Path(skip_root_file):
+            return True
+        return False
+
+    written.extend(
+        _walk_and_transform(
+            src,
+            dest,
+            content_transform=lambda c: render_tokens(c, context),
+            skip_fn=_should_skip,
+        )
+    )
+    return written
+
+
+def copy_tree_rendered_per_variant(
+    src: Path,
+    dest: Path,
+    context: Mapping[str, str],
+    variants: Sequence[str],
+    variant_key: str = "environment",
+) -> list[Path]:
+    """Copy a directory tree once per variant, adding the variant key to context.
+
+    For each variant name, copies the entire *src* tree into
+    ``dest/<variant_name>/``, augmenting the context with
+    ``{variant_key: variant_name}``.
+
+    This generalizes the "environment template" pattern — the taxonomy
+    passes ``variants=environments, variant_key="environment"``, but
+    any variant dimension can be used.
+
+    Args:
+        src: Source template directory.
+        dest: Destination parent directory.
+        context: Base token replacement context.
+        variants: Variant names (e.g., environment names: "dev", "staging", "prod").
+        variant_key: Context key for the variant name (default: "environment").
+
+    Returns:
+        List of all paths written.
+    """
+    written: list[Path] = []
+    for variant_name in variants:
+        variant_context = {**context, variant_key: variant_name}
+        variant_dir = dest / variant_name
+        written.extend(
+            _walk_and_transform(
+                src,
+                variant_dir,
+                content_transform=lambda c, ctx=variant_context: render_tokens(c, ctx),
+            )
+        )
+    return written
+
+
+def copy_tree_no_overwrite(src: Path, dest: Path) -> list[Path]:
+    """Copy a directory tree without overwriting existing files.
+
+    Files that already exist at the destination are skipped.
+    Directories are created as needed.
+
+    Args:
+        src: Source directory.
+        dest: Destination directory.
+
+    Returns:
+        List of newly created file paths.
+    """
+    written: list[Path] = []
+    for src_path in src.rglob("*"):
+        rel_path = src_path.relative_to(src)
+        dest_path = dest / rel_path
+
+        if src_path.is_dir():
+            dest_path.mkdir(parents=True, exist_ok=True)
+        elif not dest_path.exists():
+            dest_path.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(src_path, dest_path)
+            written.append(dest_path)
+
+    return written
+
+
+def copy_file(src: Path, dest: Path) -> None:
+    """Copy a single file, creating parent directories as needed.
+
+    Args:
+        src: Source file path.
+        dest: Destination file path.
+    """
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(src, dest)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _walk_and_transform(
+    src: Path,
+    dest: Path,
+    *,
+    content_transform: Callable[[str], str] | None = None,
+    path_transform: Callable[[str], str] | None = None,
+    skip_fn: Callable[[Path], bool] | None = None,
+) -> list[Path]:
+    """Walk a source tree, optionally transforming paths and content.
+
+    Args:
+        src: Source directory.
+        dest: Destination directory.
+        content_transform: Callable(str) -> str for file contents.
+        path_transform: Callable(str) -> str for relative path strings.
+        skip_fn: Callable(Path) -> bool to skip entries.
+
+    Returns:
+        List of paths written.
+    """
+    written: list[Path] = []
+
+    for src_path in src.rglob("*"):
+        rel = src_path.relative_to(src)
+
+        if skip_fn is not None and skip_fn(rel):
+            continue
+
+        rel_str = str(rel)
+        if path_transform is not None:
+            rel_str = path_transform(rel_str)
+
+        dest_path = dest / rel_str
+
+        if src_path.is_dir():
+            dest_path.mkdir(parents=True, exist_ok=True)
+        else:
+            dest_path.parent.mkdir(parents=True, exist_ok=True)
+            try:
+                content = src_path.read_text(encoding="utf-8")
+                if content_transform is not None:
+                    content = content_transform(content)
+                dest_path.write_text(content, encoding="utf-8")
+            except UnicodeDecodeError:
+                shutil.copy2(src_path, dest_path)
+            written.append(dest_path)
+
+    return written

katalyst_engine/toolkit/rendering.py

@@ -0,0 +1,58 @@
+"""Token rendering for ``{{ key }}`` template substitution.
+
+Provides the canonical implementation of the ``{{ key }}`` placeholder
+rendering used throughout the scaffolding and template systems.
+
+This is a simple regex-based substitution — NOT Jinja2. Tokens not
+found in the context are left as-is, allowing partial rendering.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Mapping
+
+_TOKEN_RE = re.compile(r"\{\{\s*(\w+)\s*\}\}")
+
+
+def render_tokens(text: str, context: Mapping[str, str]) -> str:
+    """Replace ``{{ key }}`` tokens in *text* using *context*.
+
+    Tokens not found in *context* are left as-is.
+
+    Args:
+        text: Template string containing ``{{ key }}`` tokens.
+        context: Mapping of token names to replacement values.
+
+    Returns:
+        The rendered string with tokens replaced.
+
+    Examples:
+        >>> render_tokens("Hello {{ name }}", {"name": "world"})
+        'Hello world'
+        >>> render_tokens("{{ missing }}", {})
+        '{{ missing }}'
+    """
+
+    def _replace(match: re.Match[str]) -> str:
+        return context.get(match.group(1), match.group(0))
+
+    return _TOKEN_RE.sub(_replace, text)
+
+
+def render_file(path: Path, context: Mapping[str, str]) -> str:
+    """Read a file and render its ``{{ key }}`` tokens.
+
+    Args:
+        path: Path to the template file.
+        context: Mapping of token names to replacement values.
+
+    Returns:
+        The rendered file content.
+
+    Raises:
+        OSError: If the file cannot be read.
+    """
+    content = path.read_text(encoding="utf-8")
+    return render_tokens(content, context)