refactor(pipeline): Pipeline pure-descriptor refactor — ENG-493

src/orcapod/__init__.py

@@ -2,7 +2,7 @@
     FunctionPod,
     function_pod,
 )
-from .core.sources.source_spec import SourceSpec
+from .core.nodes.source_node import SourceNode
 from .pipeline import Pipeline, PipelineJob
 
 # Subpackage re-exports for clean public API
@@ -18,7 +18,7 @@
     "function_pod",
     "Pipeline",
     "PipelineJob",
-    "SourceSpec",
+    "SourceNode",
     "databases",
     "nodes",
     "operators",

src/orcapod/core/base.py

@@ -201,6 +201,17 @@ def __eq__(self, other: object) -> bool:
 
         return self.identity_structure() == other.identity_structure()
 
+    def _invalidate_content_hash_cache(self) -> None:
+        """Invalidate the cached content hash.
+
+        Call this after any mutation that changes the object's semantic
+        content so that the next call to ``content_hash()`` recomputes
+        from scratch.  Subclasses must use this method rather than
+        accessing ``_content_hash_cache`` directly.
+        """
+        self._content_hash_cache.clear()
+        self._cached_int_hash = None
+
 
 class PipelineElementBase(DataContextMixin, ABC):
     """
@@ -270,6 +281,15 @@ def pipeline_resolver(obj: Any) -> ContentHash:
             )
         return self._pipeline_hash_cache[cache_key]
 
+    def _invalidate_pipeline_hash_cache(self) -> None:
+        """Invalidate the cached pipeline hash.
+
+        Call this after any structural mutation (e.g. attaching a database)
+        that changes this element's pipeline identity.  Subclasses must use
+        this method rather than accessing ``_pipeline_hash_cache`` directly.
+        """
+        self._pipeline_hash_cache.clear()
+
 
 class TemporalMixin:
     """

src/orcapod/core/nodes/__init__.py

@@ -1,14 +1,22 @@
 from typing import TypeAlias
 
-from .function_node import FunctionNode
-from .operator_node import OperatorNode
-from .source_node import SourceNode
+from .function_node import FunctionJobNode, FunctionNode, FunctionNodeBase
+from .operator_node import OperatorJobNode, OperatorNode, OperatorNodeBase
+from .source_node import SourceJobNode, SourceNode, SourceNodeBase
 
 GraphNode: TypeAlias = SourceNode | FunctionNode | OperatorNode
+JobNode: TypeAlias = SourceJobNode | FunctionJobNode | OperatorJobNode
 
 __all__ = [
+    "FunctionJobNode",
     "FunctionNode",
+    "FunctionNodeBase",
     "GraphNode",
+    "JobNode",
+    "OperatorJobNode",
     "OperatorNode",
+    "OperatorNodeBase",
+    "SourceJobNode",
     "SourceNode",
+    "SourceNodeBase",
 ]