starforge-kernel 0.1.0__py3-none-any.whl

starforge/__init__.py

@@ -0,0 +1,86 @@
+"""*Forge — pipeline canvas for the repo you already have open.
+
+This top-level module is the entire public surface that user code touches.
+It must import in microseconds and depend on nothing: the decorator lives in
+production codebases and has to be free. Everything heavy (indexer, engine,
+kernel) lives in submodules that only *Forge itself* imports.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["block", "progress", "BLOCK_ATTR"]
+
+#: Attribute set on decorated functions. The AST indexer matches the decorator
+#: syntactically and never imports user code; this runtime tag exists so user
+#: code and future runtime introspection can also recognize blocks.
+BLOCK_ATTR = "__starforge_block__"
+
+
+def block(fn=None, *, label=None, category=None, outputs=None):
+    """Register a function as a *Forge block.
+
+    Usable bare or with keyword arguments::
+
+        @block
+        def clean(raw: pd.DataFrame) -> pd.DataFrame: ...
+
+        @block(label="Clean AUC Matrix", category="QC", outputs=("clean", "stats"))
+        def clean_auc(raw, min_coverage: float = 0.8): ...
+
+    The decorated function is returned unchanged — behavior under pytest, in
+    CI, or in production is identical whether or not *Forge is anywhere near.
+
+    Args:
+        label: Palette display name. Defaults to the function name, title-cased.
+        category: Palette grouping. Defaults to the defining module's path.
+        outputs: Names for multiple return values (function must return a tuple
+            of the same length). Defaults to a single output named "output".
+
+    Note for palette metadata: the indexer reads ``label``/``category``/
+    ``outputs`` from the *source*, so they must be literals at the decoration
+    site to appear in the palette.
+    """
+
+    def apply(f):
+        setattr(
+            f,
+            BLOCK_ATTR,
+            {
+                "label": label,
+                "category": category,
+                "outputs": tuple(outputs) if outputs is not None else None,
+            },
+        )
+        return f
+
+    if fn is not None:
+        return apply(fn)
+    return apply
+
+
+#: Installed by the *Forge run worker around each block call; None everywhere
+#: else, which keeps progress() a guaranteed no-op in pytest/CI/production.
+_progress_hook = None
+
+
+def progress(current=None, total=None, label=None):
+    """Report block progress to the *Forge canvas.
+
+    Call freely inside a block::
+
+        for i, chunk in enumerate(chunks):
+            progress(i + 1, len(chunks), "fitting folds")
+            ...
+
+    Outside a *Forge run this does nothing and costs one attribute read —
+    safe to leave in production code. Any combination of arguments works:
+    (current, total) renders a determinate bar, label alone updates the text.
+    """
+    hook = _progress_hook
+    if hook is not None:
+        try:
+            hook(current, total, label)
+        except Exception:
+            pass  # progress must never break user code

starforge/core/checkpoints.py

@@ -0,0 +1,178 @@
+"""Checkpoint store under ``<workspace>/.forge/checkpoints/``.
+
+One directory per history hash (truncated to 32 hex chars — 128 bits — to
+stay friendly to Windows path limits):
+
+    .forge/checkpoints/<hash32>/
+    ├── provenance.json     # written LAST: its presence marks completeness
+    └── outputs/<name>.<ext per serializer>
+
+The store also owns ``.forge/.gitignore`` so checkpoints and caches never
+land in the user's repo history while ``pipelines/`` remains committable.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import shutil
+import time
+from typing import Any
+
+from starforge.core import figures as figmod
+from starforge.core import previews, serializers
+
+FORGE_DIR = ".forge"
+GITIGNORE_BODY = "checkpoints/\ncache/\n"
+
+
+class CheckpointStore:
+    def __init__(self, workspace: str | Path) -> None:
+        self.workspace = Path(workspace)
+        self.forge_dir = self.workspace / FORGE_DIR
+        self.base = self.forge_dir / "checkpoints"
+
+    def ensure_layout(self) -> None:
+        (self.forge_dir / "pipelines").mkdir(parents=True, exist_ok=True)
+        (self.forge_dir / "cache").mkdir(parents=True, exist_ok=True)
+        self.base.mkdir(parents=True, exist_ok=True)
+        gitignore = self.forge_dir / ".gitignore"
+        if not gitignore.exists():
+            gitignore.write_text(GITIGNORE_BODY, encoding="utf-8")
+
+    def dir_for(self, history_hash: str) -> Path:
+        return self.base / history_hash[:32]
+
+    def exists(self, history_hash: str) -> bool:
+        return (self.dir_for(history_hash) / "provenance.json").is_file()
+
+    def read_provenance(self, history_hash: str) -> dict[str, Any]:
+        path = self.dir_for(history_hash) / "provenance.json"
+        return json.loads(path.read_text(encoding="utf-8"))
+
+    def write(
+        self,
+        history_hash: str,
+        provenance: dict[str, Any],
+        outputs: dict[str, Any],
+        pickle_enabled: bool = False,
+        side_figures: list[Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Persist outputs then provenance (in that order, for atomicity).
+        Returns the output manifest, including ephemeral entries.
+
+        ``side_figures`` are figures the block created or showed without
+        returning them (plt.show() and friends); they render to artifacts
+        recorded under the provenance ``figures`` key."""
+        directory = self.dir_for(history_hash)
+        outputs_dir = directory / "outputs"
+        directory.mkdir(parents=True, exist_ok=True)
+        manifest = []
+        for name, value in outputs.items():
+            entry = serializers.save_value(value, outputs_dir, name, pickle_enabled=pickle_enabled)
+            try:
+                # Previews ride inside provenance.json so the stdlib-only
+                # kernel can serve them without deserializing data. Computed
+                # for ephemeral outputs too — their only window is right now.
+                if entry.get("artifact"):
+                    entry["preview"] = {
+                        "kind": "figure",
+                        "file": entry["artifact"]["file"],
+                        "format": entry["artifact"]["kind"],
+                    }
+                else:
+                    entry["preview"] = previews.build_preview(value)
+            except Exception:
+                entry["preview"] = {"kind": "text", "text": f"<preview failed for {type(value).__name__}>"}
+            manifest.append(entry)
+
+        rendered_figures: list[dict[str, Any]] = []
+        for i, fig in enumerate(side_figures or []):
+            try:
+                artifact = figmod.render_figure(fig, outputs_dir, f"figure_{i}")
+            except Exception:
+                artifact = None
+            if artifact is not None:
+                rendered_figures.append(artifact)
+
+        record = dict(provenance)
+        record["history_hash"] = history_hash
+        record["outputs"] = manifest
+        record["figures"] = rendered_figures
+        record["dir"] = directory.relative_to(self.workspace).as_posix()
+        path = directory / "provenance.json"
+        tmp = directory / "provenance.json.tmp"
+        tmp.write_text(json.dumps(record, indent=2, default=repr), encoding="utf-8")
+        tmp.replace(path)
+        return manifest
+
+    def output_entry(self, history_hash: str, name: str) -> dict[str, Any]:
+        for entry in self.read_provenance(history_hash).get("outputs", []):
+            if entry.get("name") == name:
+                return entry
+        raise KeyError(f"checkpoint {history_hash[:12]} has no output named '{name}'")
+
+    def load_output(self, history_hash: str, name: str) -> Any:
+        """Raises serializers.EphemeralValueError for non-persisted outputs."""
+        entry = self.output_entry(history_hash, name)
+        return serializers.load_value(self.dir_for(history_hash) / "outputs", entry)
+
+    def is_ephemeral(self, history_hash: str, name: str) -> bool:
+        try:
+            entry = self.output_entry(history_hash, name)
+        except (KeyError, FileNotFoundError, json.JSONDecodeError):
+            return True
+        return entry.get("serializer") == serializers.EPHEMERAL
+
+    def touch(self, history_hash: str) -> None:
+        """Bump the checkpoint dir's mtime so LRU GC sees reuse as recency."""
+        try:
+            os.utime(self.dir_for(history_hash))
+        except OSError:
+            pass
+
+    def gc(self, max_bytes: int) -> dict[str, int]:
+        """Least-recently-used eviction down to ``max_bytes`` total.
+
+        Deleting a live checkpoint is always safe — the node just reads as
+        stale and recomputes — so a plain LRU needs no liveness analysis.
+        Returns {"freed_bytes", "deleted", "remaining_bytes"}.
+        """
+        entries: list[tuple[float, int, Path]] = []
+        total = 0
+        if self.base.is_dir():
+            for directory in self.base.iterdir():
+                if not directory.is_dir():
+                    continue
+                size = sum(f.stat().st_size for f in directory.rglob("*") if f.is_file())
+                try:
+                    mtime = directory.stat().st_mtime
+                except OSError:
+                    continue
+                entries.append((mtime, size, directory))
+                total += size
+
+        freed = 0
+        deleted = 0
+        entries.sort()  # oldest first
+        for _mtime, size, directory in entries:
+            if total - freed <= max_bytes:
+                break
+            shutil.rmtree(directory, ignore_errors=True)
+            freed += size
+            deleted += 1
+        return {"freed_bytes": freed, "deleted": deleted, "remaining_bytes": total - freed}
+
+    def clean_run_specs(self, max_age_seconds: float = 86400.0) -> None:
+        """Run-spec files are one-shot worker inputs; sweep the stale ones."""
+        runs_dir = self.forge_dir / "cache" / "runs"
+        if not runs_dir.is_dir():
+            return
+        cutoff = time.time() - max_age_seconds
+        for spec in runs_dir.glob("*.json"):
+            try:
+                if spec.stat().st_mtime < cutoff:
+                    spec.unlink()
+            except OSError:
+                continue

starforge/core/figures.py

@@ -0,0 +1,119 @@
+"""Figure capture and artifact rendering.
+
+The notebook muscle memory is ``plt.plot(...); plt.show()`` — or no show()
+at all. The worker honors it with zero code changes: matplotlib runs on the
+Agg backend, and :func:`capture` sweeps every figure that exists after the
+block call that didn't exist before (``plt.show`` is a no-op under Agg, so
+"shown" figures are still open when we sweep). Plotly's ``fig.show()`` is
+intercepted by patching ``plotly.io.show`` while the block runs.
+
+Captured and returned figures render to checkpoint artifacts — matplotlib →
+PNG, plotly → self-contained HTML — and are closed afterward so a long run
+never accumulates canvases.
+
+Import discipline: stdlib-only at import time; matplotlib/plotly are only
+touched when the user's process already loaded them.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from pathlib import Path
+import sys
+from typing import Any, Iterator
+
+
+def _pyplot() -> Any | None:
+    return sys.modules.get("matplotlib.pyplot")
+
+
+def _root_module(value: Any) -> str:
+    return type(value).__module__.split(".")[0]
+
+
+@dataclass
+class CapturedFigures:
+    matplotlib: list[Any] = field(default_factory=list)
+    plotly: list[Any] = field(default_factory=list)
+
+    def all_objects(self) -> list[Any]:
+        return [*self.matplotlib, *self.plotly]
+
+
+@contextmanager
+def capture() -> Iterator[CapturedFigures]:
+    """Collect figures created (matplotlib) or shown (plotly) inside the
+    block call. The matplotlib sweep also catches figures created during the
+    block module's first import, since the import happens inside this
+    context in the runner."""
+    captured = CapturedFigures()
+
+    plt = _pyplot()
+    before: set[int] = set(plt.get_fignums()) if plt is not None else set()
+
+    pio = sys.modules.get("plotly.io")
+    original_show = getattr(pio, "show", None) if pio is not None else None
+    if pio is not None and original_show is not None:
+
+        def _grab(fig: Any, *args: Any, **kwargs: Any) -> None:
+            captured.plotly.append(fig)
+
+        pio.show = _grab
+
+    try:
+        yield captured
+    finally:
+        if pio is not None and original_show is not None:
+            pio.show = original_show
+        plt = _pyplot()  # may have been imported during the call
+        if plt is not None:
+            for num in plt.get_fignums():
+                if num not in before:
+                    captured.matplotlib.append(plt.figure(num))
+
+
+def as_figure(value: Any) -> Any | None:
+    """Return a renderable figure for ``value``, or None.
+
+    Accepts matplotlib Figures, matplotlib Axes (``sns.heatmap`` et al.
+    return Axes — we render their parent figure), and plotly figures.
+    """
+    root = _root_module(value)
+    if root == "matplotlib":
+        if hasattr(value, "savefig"):
+            return value
+        parent = getattr(value, "figure", None)  # Axes and friends
+        if parent is not None and hasattr(parent, "savefig"):
+            return parent
+    if root == "plotly" and hasattr(value, "write_html"):
+        return value
+    return None
+
+
+def render_figure(value: Any, directory: Path, basename: str) -> dict[str, Any] | None:
+    """Render to ``directory/basename.(png|html)``; returns the artifact
+    entry ``{"file", "kind"}`` or None if ``value`` is not a figure."""
+    fig = as_figure(value)
+    if fig is None:
+        return None
+    directory.mkdir(parents=True, exist_ok=True)
+    if _root_module(fig) == "matplotlib":
+        filename = f"{basename}.png"
+        fig.savefig(directory / filename, dpi=110, bbox_inches="tight", facecolor=fig.get_facecolor())
+        return {"file": filename, "kind": "image"}
+    filename = f"{basename}.html"
+    fig.write_html(directory / filename, include_plotlyjs=True, full_html=True)
+    return {"file": filename, "kind": "html"}
+
+
+def close_figures(figures: list[Any]) -> None:
+    plt = _pyplot()
+    if plt is None:
+        return
+    for fig in figures:
+        if _root_module(fig) == "matplotlib":
+            try:
+                plt.close(fig)
+            except Exception:
+                pass

starforge/core/previews.py

@@ -0,0 +1,109 @@
+"""Cropped, JSON-safe output previews, computed at checkpoint-write time.
+
+Previews are precomputed artifacts stored inside ``provenance.json`` — the
+kernel serves them by reading a file, never by deserializing data (it stays
+stdlib-only and instant). Because they're built while the value is in the
+worker's hands, even EPHEMERAL outputs get a preview of their last run.
+
+Everything emitted here must survive strict JSON.parse on the TypeScript
+side: NaN/Infinity are stringified, containers are size-capped, and unknown
+objects fall back to repr.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+MAX_ROWS = 8
+MAX_COLS = 10
+MAX_ITEMS = 50
+MAX_DEPTH = 5
+MAX_CELL_CHARS = 120
+MAX_TEXT_CHARS = 600
+MAX_VALUE_CHARS = 2000
+
+
+def _cell(value: Any) -> Any:
+    """One scalar table/array cell, strict-JSON safe."""
+    if isinstance(value, bool) or value is None:
+        return value
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return value if value == value and abs(value) != float("inf") else str(value)
+    text = value if isinstance(value, str) else repr(value)
+    return text[:MAX_CELL_CHARS] + ("…" if len(text) > MAX_CELL_CHARS else "")
+
+
+def _sanitize(value: Any, depth: int = 0) -> Any:
+    if depth >= MAX_DEPTH:
+        return _cell(value)
+    if isinstance(value, dict):
+        items = list(value.items())[:MAX_ITEMS]
+        out = {str(k)[:MAX_CELL_CHARS]: _sanitize(v, depth + 1) for k, v in items}
+        if len(value) > MAX_ITEMS:
+            out["…"] = f"+{len(value) - MAX_ITEMS} more"
+        return out
+    if isinstance(value, (list, tuple)):
+        out = [_sanitize(v, depth + 1) for v in value[:MAX_ITEMS]]
+        if len(value) > MAX_ITEMS:
+            out.append(f"… +{len(value) - MAX_ITEMS} more")
+        return out
+    return _cell(value)
+
+
+def _root_type_module(value: Any) -> str:
+    return type(value).__module__.split(".")[0]
+
+
+def build_preview(value: Any) -> dict[str, Any]:
+    if _root_type_module(value) == "pandas":
+        import pandas as pd
+
+        frame = value.to_frame() if isinstance(value, pd.Series) else value
+        if isinstance(frame, pd.DataFrame):
+            columns = [str(c) for c in frame.columns[:MAX_COLS]]
+            head = frame.iloc[:MAX_ROWS, :MAX_COLS]
+            return {
+                "kind": "table",
+                "shape": [int(frame.shape[0]), int(frame.shape[1])],
+                "columns": columns,
+                "columns_truncated": frame.shape[1] > MAX_COLS,
+                "index": [_cell(i) for i in head.index.tolist()],
+                "rows": [[_cell(v) for v in row] for row in head.itertuples(index=False, name=None)],
+            }
+
+    if _root_type_module(value) == "numpy":
+        import numpy as np
+
+        if isinstance(value, np.ndarray):
+            corner = value
+            if corner.ndim == 0:
+                corner_list: Any = _cell(corner.item())
+            else:
+                slicer = tuple(slice(0, MAX_ROWS) for _ in range(corner.ndim))
+                corner_list = _sanitize(corner[slicer].tolist())
+            return {
+                "kind": "array",
+                "dtype": str(value.dtype),
+                "shape": list(value.shape),
+                "corner": corner_list,
+            }
+        if isinstance(value, np.generic):
+            return {"kind": "value", "value": _cell(value.item())}
+
+    if isinstance(value, (dict, list, tuple, str, int, float, bool)) or value is None:
+        sanitized = _sanitize(value)
+        try:
+            encoded = json.dumps(sanitized, allow_nan=False)
+        except (TypeError, ValueError):
+            encoded = None
+        if encoded is not None:
+            if len(encoded) > MAX_VALUE_CHARS:
+                return {"kind": "text", "text": encoded[:MAX_VALUE_CHARS] + "…"}
+            return {"kind": "value", "value": sanitized}
+
+    # Arbitrary objects: an honest repr, marked as text rather than data.
+    text = repr(value)
+    return {"kind": "text", "text": text[:MAX_TEXT_CHARS] + ("…" if len(text) > MAX_TEXT_CHARS else "")}

starforge/core/provenance.py

@@ -0,0 +1,192 @@
+"""History-hash computation — the Tier 2 staleness recipe from DESIGN.md §7.
+
+history_hash = sha256(canonical_json({
+    fn:      source hash of the decorated function (AST-normalized),
+    closure: hash of the defining module's repo import-closure,
+    env:     environment fingerprint (python version + dependency files),
+    params:  literal params for UNCONNECTED parameters only,
+    inputs:  {param_name: [parent_history_hash, source_output]},
+}))
+
+A node is stale iff no checkpoint exists for its computed hash. Everything
+here is pure stdlib and cheap enough to recompute on every document edit.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import hashlib
+import json
+from pathlib import Path
+import sys
+from typing import Any, Callable
+
+from starforge.core.spec import PipelineDoc
+from starforge.index.scanner import WorkspaceIndex
+
+#: Doc-native nodes that execute without importing user code. Constants are
+#: the first; the snippet node (DESIGN.md §10) will join this namespace.
+BUILTIN_PREFIX = "builtin:"
+BUILTINS = {"builtin:constant"}
+
+#: Dependency manifests folded into the environment fingerprint. pyproject is
+#: deliberately excluded — version bumps would invalidate every checkpoint.
+ENV_FILES = (
+    "requirements.txt",
+    "requirements.lock",
+    "poetry.lock",
+    "uv.lock",
+    "Pipfile.lock",
+)
+
+
+def canonical_json(value: Any) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), default=repr)
+
+
+def _sha(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def env_fingerprint(workspace: str | Path) -> str:
+    workspace = Path(workspace)
+    parts = [f"python:{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"]
+    for name in ENV_FILES:
+        path = workspace / name
+        if path.is_file():
+            try:
+                parts.append(f"{name}:{hashlib.sha256(path.read_bytes()).hexdigest()}")
+            except OSError:
+                continue
+    return _sha("\n".join(parts))
+
+
+@dataclass
+class NodeState:
+    history_hash: str | None = None
+    stale: bool = True
+    #: Human-readable reasons the node cannot hash or run (missing block,
+    #: cycle membership, bad edge target, ...). Empty means healthy.
+    problems: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"history_hash": self.history_hash, "stale": self.stale, "problems": self.problems}
+
+
+def toposort(doc: PipelineDoc) -> tuple[list[str], set[str]]:
+    """Kahn's algorithm. Returns (ordered_ids, ids_stuck_in_cycles)."""
+    indegree = {n.id: 0 for n in doc.nodes}
+    children: dict[str, list[str]] = {n.id: [] for n in doc.nodes}
+    for edge in doc.edges:
+        if edge.source in indegree and edge.target in indegree:
+            indegree[edge.target] += 1
+            children[edge.source].append(edge.target)
+    ready = sorted(nid for nid, deg in indegree.items() if deg == 0)
+    order: list[str] = []
+    while ready:
+        nid = ready.pop(0)
+        order.append(nid)
+        for child in children[nid]:
+            indegree[child] -= 1
+            if indegree[child] == 0:
+                ready.append(child)
+        ready.sort()  # determinism beats micro-speed at canvas scale
+    return order, {nid for nid, deg in indegree.items() if deg > 0}
+
+
+#: Staleness tiers (DESIGN.md §7). The closure component per tier:
+#:   T0 — function body only (cheapest, misses helper edits entirely)
+#:   T1 — + the defining module (catches same-file helpers)
+#:   T2 — + the repo import closure (default; safe over-invalidation)
+TIERS = ("T0", "T1", "T2")
+
+
+def _closure_component(tier: str, index: WorkspaceIndex, module: str) -> str:
+    if tier == "T0":
+        return ""
+    if tier == "T1":
+        info = index.modules.get(module)
+        return (info.ast_hash or info.file_hash) if info else ""
+    return index.closure_hash(module)
+
+
+def compute_states(
+    doc: PipelineDoc,
+    index: WorkspaceIndex,
+    env_fp: str,
+    checkpoint_exists: Callable[[str], bool],
+    tier: str = "T2",
+) -> dict[str, NodeState]:
+    """Hash every node and decide staleness. Never raises on a sick document —
+    problems are reported per-node so the canvas can render them in place."""
+    blocks = index.blocks
+    states: dict[str, NodeState] = {n.id: NodeState() for n in doc.nodes}
+    order, cyclic = toposort(doc)
+    for nid in cyclic:
+        states[nid].problems.append("part of a dependency cycle")
+
+    for nid in order:
+        node = doc.node(nid)
+        state = states[nid]
+
+        if node.block.startswith(BUILTIN_PREFIX):
+            if node.block not in BUILTINS:
+                state.problems.append(f"unknown builtin '{node.block}'")
+                continue
+            if doc.in_edges(nid):
+                state.problems.append("Constant is a source node and takes no inputs")
+                continue
+            # Deliberately excludes env/closure: a constant's identity is its
+            # value, so checkpoints survive dependency upgrades and edits.
+            state.history_hash = _sha(canonical_json({"builtin": node.block, "params": node.params}))
+            state.stale = not checkpoint_exists(state.history_hash)
+            continue
+
+        info = blocks.get(node.block)
+        if info is None:
+            state.problems.append(f"block '{node.block}' not found in workspace (decorator removed or file deleted?)")
+            continue
+
+        param_names = {p.name for p in info.params}
+        inputs: dict[str, list[str]] = {}
+        broken = False
+        for edge in doc.in_edges(nid):
+            parent_state = states.get(edge.source)
+            if parent_state is None or parent_state.history_hash is None:
+                state.problems.append(f"input '{edge.target_param}' depends on unresolvable node '{edge.source}'")
+                broken = True
+                continue
+            if edge.target_param not in param_names:
+                state.problems.append(f"edge targets unknown parameter '{edge.target_param}'")
+                broken = True
+                continue
+            if edge.target_param in inputs:
+                state.problems.append(f"parameter '{edge.target_param}' has multiple incoming edges")
+                broken = True
+                continue
+            parent_block = blocks.get(doc.node(edge.source).block)
+            if parent_block is not None and edge.source_output not in parent_block.outputs:
+                state.problems.append(
+                    f"edge expects output '{edge.source_output}' but '{parent_block.label}' produces {parent_block.outputs}"
+                )
+                broken = True
+                continue
+            inputs[edge.target_param] = [parent_state.history_hash, edge.source_output]
+        if broken:
+            continue
+
+        literals = {k: v for k, v in node.params.items() if k not in inputs}
+        state.history_hash = _sha(
+            canonical_json(
+                {
+                    "fn": info.source_hash,
+                    "closure": _closure_component(tier, index, info.module),
+                    "env": env_fp,
+                    "params": literals,
+                    "inputs": inputs,
+                }
+            )
+        )
+        state.stale = not checkpoint_exists(state.history_hash)
+
+    return states