katalyst-engine 3.1.0__tar.gz → 4.1.0__tar.gz

{katalyst_engine-3.1.0 → katalyst_engine-4.1.0}/.gitignore

@@ -103,3 +103,10 @@ stack-tests/test-results/
 # Generated artifacts (rebuild with `just generate-schemas`)
 taxonomy/src/katalyst_taxonomy/engine/generated/
 .worktrees/
+.plan-74-75-76-77.md
+.HANDOFF-scaffolding-wiring.md
+.HANDOFF-2-cicd-migration.md
+.HANDOFF-action-execution-fixes.md
+.HANDOFF-bdd-coverage.md
+.HANDOFF-*.md
+docs/superpowers/

{katalyst_engine-3.1.0 → katalyst_engine-4.1.0}/CHANGELOG.md

@@ -10,6 +10,18 @@ workspace packages. Tags use the `engine-vX.Y.Z` prefix.
 
 ---
 
+## [4.1.0] -- 2026-06-26
+
+### Added
+
+- **`FieldSpec.allowed_values`** -- a generic, taxonomy-agnostic field-constraint mechanism. When non-empty, it declares the permitted values for a field; empty (the default `()`) means unconstrained. Consumers (e.g. the taxonomy v2 linter) project it to a JSON Schema `enum`. The engine holds only the mechanism; domain-specific values (such as the `work_item` lifecycle) live in the forge consumer, keeping the engine taxonomy-agnostic. Additive and backward-compatible. (#143, #138)
+
+## [4.0.0] -- 2026-06-16
+
+### Removed
+
+- **BREAKING: Removed the `scaffoldable` flag from the node-model API.** The `NodeDefinition.scaffoldable` field and the `SchemaRegistry.is_scaffoldable()` and `SchemaRegistry.scaffoldable_kinds()` methods are gone. Scaffolding is no longer an engine-level concept: any node kind may be scaffolded, and the decision is owned entirely by the scaffolding plugin/runtime in `katalyst-taxonomy`. Consumers that called `is_scaffoldable()` / `scaffoldable_kinds()` or read `NodeDefinition.scaffoldable` must drop those calls — scaffolding capability is determined by the taxonomy layer, not the engine.
+
 ## [3.1.0] -- 2026-06-11
 
 ### Added

{katalyst_engine-3.1.0 → katalyst_engine-4.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: katalyst-engine
-Version: 3.1.0
+Version: 4.1.0
 Summary: A distributed declaration framework — primitives for schema-aware, multi-source, evolvable artifact graphs
 Project-URL: Repository, https://github.com/esimplicityinc/katalyst-taxonomy
 Author: eSimplicity

{katalyst_engine-3.1.0 → katalyst_engine-4.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "katalyst-engine"
-version = "3.1.0"
+version = "4.1.0"
 description = "A distributed declaration framework — primitives for schema-aware, multi-source, evolvable artifact graphs"
 readme = "README.md"
 license = { text = "Proprietary" }

{katalyst_engine-3.1.0 → katalyst_engine-4.1.0}/src/katalyst_engine/schema/definition.py

@@ -44,6 +44,11 @@ class FieldSpec(BaseModel, frozen=True):
     ref_target_kind: str = ""
     """If field_type is 'ref', the kind of Evolvable it references."""
 
+    allowed_values: tuple[str, ...] = ()
+    """If non-empty, the permitted values for this field, projected to a JSON
+    Schema ``enum`` by consumers. Empty means unconstrained. The engine holds
+    only the mechanism; domain-specific values are supplied by consumers."""
+
 
 class ParentRule(BaseModel, frozen=True):
     """Declares what kinds are allowed as parents of a node kind.
@@ -120,9 +125,6 @@ class NodeDefinition(Definitive, frozen=True):
     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."""
 

{katalyst_engine-3.1.0 → katalyst_engine-4.1.0}/src/katalyst_engine/schema/registry.py

@@ -168,24 +168,11 @@ class SchemaRegistry:
         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 [

{katalyst_engine-3.1.0 → katalyst_engine-4.1.0}/tests/bundle/test_path_loader.py

@@ -62,7 +62,6 @@ def _write_bundle(root: Path, *, deps: str = '"katalyst-engine>=3.0,<4"') -> Pat
                 is_root=True,
                 is_leaf=True,
                 is_extension=False,
-                scaffoldable=False,
                 clonable=False,
                 display_label="Demo Thing",
                 display_label_plural="Demo Things",

{katalyst_engine-3.1.0 → katalyst_engine-4.1.0}/tests/schema/test_definition.py

@@ -134,22 +134,29 @@ class TestNodeDefinition:
         assert restored.describes_kind == nd.describes_kind
         assert len(restored.fields) == len(nd.fields)
 
-    def test_scaffoldable_and_clonable_defaults(self) -> None:
+    def test_clonable_default(self) -> None:
         nd = NodeDefinition(
             identity=_id("node_definition", "system"),
             describes_kind="system",
         )
-        assert nd.scaffoldable is False
         assert nd.clonable is False
 
-    def test_scaffoldable_and_clonable_set(self) -> None:
+    def test_no_scaffoldable_field(self) -> None:
+        # Scaffolding is a plugin concern — the engine NodeDefinition must NOT
+        # carry a scaffoldable flag (regression guard for the extraction).
+        nd = NodeDefinition(
+            identity=_id("node_definition", "layer"),
+            describes_kind="layer",
+        )
+        assert not hasattr(nd, "scaffoldable")
+        assert "scaffoldable" not in type(nd).model_fields
+
+    def test_clonable_set(self) -> None:
         nd = NodeDefinition(
             identity=_id("node_definition", "layer"),
             describes_kind="layer",
-            scaffoldable=True,
             clonable=True,
         )
-        assert nd.scaffoldable is True
         assert nd.clonable is True
 
     def test_display_label_defaults(self) -> None:

katalyst_engine-4.1.0/tests/schema/test_engine_boundary_guard.py

@@ -0,0 +1,49 @@
+"""Engine boundary guard: engine must stay taxonomy-agnostic.
+
+The engine holds the field-constraint MECHANISM (FieldSpec.allowed_values) but
+never taxonomy-specific VALUES (e.g. the work_item lifecycle). Those live in the
+forge consumer. This guard fails if lifecycle status literals or forge/taxonomy
+imports leak into engine/src.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+ENGINE_SRC = Path(__file__).resolve().parents[2] / "src" / "katalyst_engine"
+LIFECYCLE_TOKENS = (
+    "idea",
+    "proposed",
+    "accepted",
+    "planned",
+    "in_progress",
+    "blocked",
+    "delivered",
+    "validated",
+    "released",
+    "retired",
+)
+
+
+def _engine_files() -> list[Path]:
+    return list(ENGINE_SRC.rglob("*.py"))
+
+
+def test_no_lifecycle_status_literals_in_engine() -> None:
+    offenders: list[str] = []
+    for path in _engine_files():
+        text = path.read_text(encoding="utf-8")
+        present = [t for t in LIFECYCLE_TOKENS if t in text]
+        if len(present) >= 2:
+            offenders.append(f"{path.name}: {present}")
+    assert not offenders, f"Lifecycle values leaked into engine: {offenders}"
+
+
+def test_engine_does_not_import_consumers() -> None:
+    import_re = re.compile(r"^\s*(?:import|from)\s+katalyst_(?:forge|taxonomy)\b", re.MULTILINE)
+    offenders: list[str] = []
+    for path in _engine_files():
+        if import_re.search(path.read_text(encoding="utf-8")):
+            offenders.append(path.name)
+    assert not offenders, f"Engine imports consumer packages: {offenders}"

katalyst_engine-4.1.0/tests/schema/test_fieldspec_allowed_values.py

@@ -0,0 +1,23 @@
+"""WP-3 (#3 mechanism): FieldSpec.allowed_values generic constraint."""
+
+from __future__ import annotations
+
+from katalyst_engine.schema.definition import FieldSpec
+
+
+def test_allowed_values_default_empty() -> None:
+    assert FieldSpec(name="status").allowed_values == ()
+
+
+def test_allowed_values_set() -> None:
+    f = FieldSpec(name="status", allowed_values=("a", "b"))
+    assert f.allowed_values == ("a", "b")
+
+
+def test_allowed_values_frozen() -> None:
+    f = FieldSpec(name="status", allowed_values=("a",))
+    try:
+        f.allowed_values = ("c",)  # type: ignore[misc]
+        raise AssertionError("Expected frozen")  # noqa: TRY301
+    except Exception:
+        pass