From d95f039e3b61c7ea498010aa3a8ab7a28b589d4a Mon Sep 17 00:00:00 2001
From: Florian Rupprecht <floruppr@gmail.com>
Date: Fri, 3 Apr 2026 16:13:53 -0400
Subject: [PATCH] Add TypedDicts for resolve_functional and resolve_metrics
 return types

Unifies the pattern across all resolve functions: resolve_qc already
returned QCInputs (TypedDict), now resolve_functional returns
FunctionalInputs and resolve_metrics returns MetricsInputs. This gives
callers proper type safety when accessing resolved paths.

Part of #259.
---
 src/rbc/bids/__init__.py   |  9 ++++++---
 src/rbc/bids/functional.py | 15 +++++++++++++--
 src/rbc/bids/metrics.py    | 12 ++++++++++--
 3 files changed, 29 insertions(+), 7 deletions(-)

diff --git a/src/rbc/bids/__init__.py b/src/rbc/bids/__init__.py
index e898d46c..036aebcc 100644
--- a/src/rbc/bids/__init__.py
+++ b/src/rbc/bids/__init__.py
@@ -26,9 +26,9 @@
 )
 from rbc.bids.anatomical import export_anatomical
 from rbc.bids.builder import Bids
-from rbc.bids.functional import export_functional, resolve_functional
-from rbc.bids.metrics import export_metrics, resolve_metrics
-from rbc.bids.qc import export_qc, resolve_qc
+from rbc.bids.functional import FunctionalInputs, export_functional, resolve_functional
+from rbc.bids.metrics import MetricsInputs, export_metrics, resolve_metrics
+from rbc.bids.qc import QCInputs, export_qc, resolve_qc
 from rbc.bids.query import find_file, find_files, get_extra_entity, load_table
 
 __all__ = [
@@ -40,7 +40,10 @@
     "Datatype",
     "EntityKwargs",
     "Extension",
+    "FunctionalInputs",
+    "MetricsInputs",
     "Modality",
+    "QCInputs",
     "Suffix",
     "TemplateSpace",
     "bids_name",
diff --git a/src/rbc/bids/functional.py b/src/rbc/bids/functional.py
index 0386b781..08e59700 100644
--- a/src/rbc/bids/functional.py
+++ b/src/rbc/bids/functional.py
@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, TypedDict
 
 from rbc.bids import Suffix, TemplateSpace, bids_safe_label
 
@@ -16,10 +16,21 @@
     from rbc.workflows.functional import FunctionalOutputs
 
 
+class FunctionalInputs(TypedDict):
+    """Resolved anatomical inputs for the functional workflow."""
+
+    t1w_brain: Path
+    wm_bbr_mask: Path
+    brain_mask: Path
+    csf_mask: Path
+    wm_mask: Path
+    anat_to_template: Path
+
+
 def resolve_functional(
     anat_q: Bids,
     anat_df: pl.DataFrame,
-) -> dict[str, Path]:
+) -> FunctionalInputs:
     """Resolve anatomical prerequisites needed by functional preprocessing.
 
     Args:
diff --git a/src/rbc/bids/metrics.py b/src/rbc/bids/metrics.py
index 9d0fbc55..b2bda843 100644
--- a/src/rbc/bids/metrics.py
+++ b/src/rbc/bids/metrics.py
@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, TypedDict
 
 from rbc.bids import Suffix, bids_safe_label
 
@@ -16,12 +16,20 @@
     from rbc.workflows.metrics import MetricsOutputs
 
 
+class MetricsInputs(TypedDict):
+    """Resolved functional inputs for the metrics workflow."""
+
+    template_brain_mask: Path
+    regressed_bold: Path
+    cleaned_bold: Path
+
+
 def resolve_metrics(
     mni_q: Bids,
     deriv_df: pl.DataFrame,
     *,
     regressor: str,
-) -> dict[str, Path]:
+) -> MetricsInputs:
     """Resolve functional derivatives needed by the metrics workflow.
 
     Args: