"""Run-id helpers and per-step artifact directory resolution.

Each pipeline run gets a single run_id (timestamp-based by default). Each step
writes its intermediate artifacts to <step>/output/<run_id>/ so the state of
every step is inspectable after a run.
"""
from __future__ import annotations

from datetime import datetime
from pathlib import Path


def new_run_id() -> str:
    """Return a sortable run id like '20260430_142301'."""
    return datetime.now().strftime("%Y%m%d_%H%M%S")


def step_output_dir(step_output_root: Path, run_id: str) -> Path:
    """Return <step>/output/<run_id>/, creating it if needed."""
    d = step_output_root / run_id
    d.mkdir(parents=True, exist_ok=True)
    return d