flextool 4.0.0__py3-none-any.whl

flextool/gui/ui_metrics.py

@@ -0,0 +1,420 @@
+"""Central font metrics + scaling helpers for the FlexTool GUI.
+
+All windows and dialogs should read sizes through ``get_metrics()`` so a
+single ``setup_fonts()`` call at startup controls the whole UI.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re as _re
+import tkinter as tk
+import tkinter.font as tkfont
+
+
+_GEOMETRY_RE = _re.compile(
+    r"^(?P<w>\d+)x(?P<h>\d+)"
+    r"(?:(?P<xs>[+-])(?P<x>\d+)(?P<ys>[+-])(?P<y>\d+))?$"
+)
+
+
+def clamp_geometry(
+    saved: str,
+    screen_w: int,
+    screen_h: int,
+    *,
+    min_w: int,
+    min_h: int,
+    margin: int = 40,
+) -> str | None:
+    """Sanitise a saved Tk geometry string against the current screen.
+
+    Returns ``None`` if *saved* is empty or malformed. Otherwise:
+
+    * Width/height are clamped to ``[min_w, screen_w - margin]`` and
+      ``[min_h, screen_h - margin]``.
+    * If an ``+X+Y`` offset is present, it is kept only when the window
+      would fit fully on-screen; otherwise the offset is dropped and the
+      window is placed at ``+0+0`` (the WM picks the position).
+
+    The ``margin`` reserves space for taskbars / docks.
+    """
+    if not saved:
+        return None
+    m = _GEOMETRY_RE.match(saved.strip())
+    if not m:
+        return None
+    orig_w = int(m["w"])
+    orig_h = int(m["h"])
+    w = max(min_w, min(orig_w, max(min_w, screen_w - margin)))
+    h = max(min_h, min(orig_h, max(min_h, screen_h - margin)))
+    clamped_size = (w != orig_w) or (h != orig_h)
+    if m["x"] is None:
+        return f"{w}x{h}"
+    x = int(m["x"])
+    y = int(m["y"])
+    if m["xs"] == "-":
+        x = -x
+    if m["ys"] == "-":
+        y = -y
+    # Drop the offset if the width/height had to be clamped or the window
+    # would run off-screen — saved offsets from a different resolution
+    # are not trustworthy in those cases.
+    if (
+        clamped_size
+        or x < 0
+        or y < 0
+        or x + w > screen_w
+        or y + h > screen_h - margin
+    ):
+        return f"{w}x{h}"
+    return f"{w}x{h}+{x}+{y}"
+
+
+def clamp_sash(
+    saved_px: int,
+    pane_total: int,
+    *,
+    min_px: int,
+    max_frac: float = 0.85,
+) -> int:
+    """Keep a saved sash position inside the current pane.
+
+    Returns 0 when *saved_px* is 0 or ``pane_total`` is too small to honour
+    ``min_px`` — callers should treat 0 as "leave default".
+    """
+    if saved_px <= 0 or pane_total <= 0:
+        return 0
+    upper = int(pane_total * max_frac)
+    if upper <= min_px:
+        return 0
+    return max(min_px, min(saved_px, upper))
+
+
+def rescale_pixels(saved_px: int, saved_cw: int, current_cw: int) -> int:
+    """Rescale a pixel value saved under one font metric to the current one.
+
+    Returns ``saved_px`` unchanged when ``saved_cw`` is 0 (unknown), when
+    the ratio is within 10%, or when either cw is non-positive. Otherwise
+    returns ``round(saved_px * current_cw / saved_cw)``.
+
+    Used to make saved sash positions and (optionally) window dimensions
+    survive a DPI change between sessions.
+    """
+    if saved_px <= 0 or saved_cw <= 0 or current_cw <= 0:
+        return saved_px
+    ratio = current_cw / saved_cw
+    if 0.90 <= ratio <= 1.10:
+        return saved_px
+    return round(saved_px * ratio)
+
+
+def rescale_geometry(saved: str, saved_cw: int, current_cw: int) -> str:
+    """Apply rescale_pixels to W and H in a Tk geometry string."""
+    if not saved or saved_cw <= 0 or current_cw <= 0 or saved_cw == current_cw:
+        return saved
+    m = _GEOMETRY_RE.match(saved.strip())
+    if not m:
+        return saved
+    new_w = rescale_pixels(int(m["w"]), saved_cw, current_cw)
+    new_h = rescale_pixels(int(m["h"]), saved_cw, current_cw)
+    if m["x"] is None:
+        return f"{new_w}x{new_h}"
+    xs = m["xs"]
+    ys = m["ys"]
+    return f"{new_w}x{new_h}{xs}{m['x']}{ys}{m['y']}"
+
+
+def monitor_signature(window: tk.Misc | None = None) -> str:
+    """Stable key identifying the current monitor *configuration*.
+
+    Used to remember window placements per monitor layout: a window
+    dragged onto the 4K while docked, then the laptop undocked, should not
+    have its docked offset reused on the single internal panel. The
+    signature changes whenever a monitor is added/removed/moved/resized, so
+    each configuration keeps its own saved geometry.
+
+    Built from the sorted ``WxH+X+Y`` rectangles reported by ``screeninfo``
+    (order-independent). Falls back to ``virtual:<W>x<H>`` from the Tk
+    virtual-desktop size when ``screeninfo`` is unavailable, and finally to
+    ``"virtual:unknown"`` so callers always get a usable, hashable key.
+    """
+    try:
+        from screeninfo import get_monitors
+        monitors = list(get_monitors())
+        if monitors:
+            parts = sorted(
+                f"{int(m.width)}x{int(m.height)}+{int(m.x)}+{int(m.y)}"
+                for m in monitors
+            )
+            return "|".join(parts)
+    except Exception:
+        pass
+    if window is not None:
+        try:
+            return f"virtual:{window.winfo_screenwidth()}x{window.winfo_screenheight()}"
+        except tk.TclError:
+            pass
+    return "virtual:unknown"
+
+
+def primary_monitor_bounds() -> tuple[int, int, int, int] | None:
+    """Bounds ``(x, y, w, h)`` of the primary monitor, or ``None``.
+
+    Used to place a window that has no prior position to detect a "current"
+    monitor from (e.g. the main window at first launch). Prefers the monitor
+    ``screeninfo`` flags ``is_primary``; otherwise the first enumerated one.
+    Returns ``None`` when ``screeninfo`` is unavailable or enumerates none,
+    so callers fall back to virtual-desktop sizing.
+    """
+    try:
+        from screeninfo import get_monitors
+        monitors = list(get_monitors())
+    except Exception:
+        return None
+    if not monitors:
+        return None
+    chosen = next((m for m in monitors if getattr(m, "is_primary", False)), monitors[0])
+    if chosen.width <= 1 or chosen.height <= 1:
+        return None
+    return (int(chosen.x), int(chosen.y), int(chosen.width), int(chosen.height))
+
+
+def _monitor_bounds_screeninfo(
+    window: tk.Misc,
+) -> tuple[int, int, int, int] | None:
+    """Per-monitor rectangle via the ``screeninfo`` package (flicker-free).
+
+    Picks the monitor whose rectangle contains the centre of *window*; if
+    no monitor claims the centre (e.g. the window straddles a gap), falls
+    back to the primary monitor, then the first enumerated one. Returns
+    ``None`` when ``screeninfo`` is missing or enumerates no monitors, so
+    the caller can drop to the maximise-probe.
+    """
+    try:
+        from screeninfo import get_monitors
+    except Exception:
+        return None
+    try:
+        monitors = list(get_monitors())
+    except Exception:
+        # screeninfo raises on headless / unusual display backends.
+        return None
+    if not monitors:
+        return None
+    try:
+        window.update_idletasks()
+        cx = window.winfo_x() + window.winfo_width() // 2
+        cy = window.winfo_y() + window.winfo_height() // 2
+    except tk.TclError:
+        cx = cy = None
+    chosen = None
+    if cx is not None:
+        for m in monitors:
+            if m.x <= cx < m.x + m.width and m.y <= cy < m.y + m.height:
+                chosen = m
+                break
+    if chosen is None:
+        chosen = next((m for m in monitors if getattr(m, "is_primary", False)), None)
+    if chosen is None:
+        chosen = monitors[0]
+    if chosen.width <= 1 or chosen.height <= 1:
+        return None
+    return (int(chosen.x), int(chosen.y), int(chosen.width), int(chosen.height))
+
+
+def current_monitor_bounds(window: tk.Misc) -> tuple[int, int, int, int] | None:
+    """Best-effort bounds ``(x, y, w, h)`` of the monitor showing *window*.
+
+    Tk exposes no per-monitor geometry: ``winfo_screenwidth`` /
+    ``winfo_screenheight`` report the FULL virtual desktop spanning *every*
+    monitor, so sizing a window to those values stretches it across all
+    screens (the dual-monitor "window covers both displays" bug).
+
+    Prefers the ``screeninfo`` package (flicker-free, also yields the
+    monitor's ``x``/``y`` origin). When it is unavailable or enumerates no
+    monitors, falls back to momentarily maximising *window* — the window
+    manager snaps a maximised window to the *current* monitor's usable area
+    — then reading the resulting offset/size and restoring normal state.
+
+    *window* should already be positioned (e.g. via ``geometry("+x+y")``) on
+    the target monitor before calling, so both paths pick the right display.
+    Returns ``None`` when every approach fails, so callers fall back to
+    virtual-desktop sizing (no worse than before).
+
+    Note: ``screeninfo`` reports the full monitor rectangle, not the WM work
+    area, so callers should still reserve taskbar/dock space themselves; the
+    maximise-probe path already excludes it.
+    """
+    bounds = _monitor_bounds_screeninfo(window)
+    if bounds is not None:
+        return bounds
+
+    def _set_maximised(on: bool) -> bool:
+        # Windows / macOS use state('zoomed'); most Linux WMs honour the
+        # '-zoomed' attribute. Try both; report whether either took.
+        try:
+            window.tk.call("wm", "state", window._w, "zoomed" if on else "normal")
+            return True
+        except tk.TclError:
+            pass
+        try:
+            window.tk.call("wm", "attributes", window._w, "-zoomed", "1" if on else "0")
+            return True
+        except tk.TclError:
+            return False
+
+    try:
+        window.update_idletasks()
+        if not _set_maximised(True):
+            return None
+        window.update_idletasks()
+        x = window.winfo_x()
+        y = window.winfo_y()
+        w = window.winfo_width()
+        h = window.winfo_height()
+        _set_maximised(False)
+        window.update_idletasks()
+        if w <= 1 or h <= 1:
+            return None
+        return (x, y, w, h)
+    except tk.TclError:
+        return None
+
+
+def resolve_saved_geometry(
+    geom_map: dict[str, str],
+    signature: str,
+    saved_cw: int,
+    current_cw: int,
+    screen_w: int,
+    screen_h: int,
+    *,
+    min_w: int,
+    min_h: int,
+) -> str | None:
+    """Pick the geometry saved for *signature* and make it safe to apply.
+
+    Looks up *geom_map* by the current monitor *signature*, falling back to
+    a ``"legacy"`` entry migrated from the old single-string format. The
+    result is rescaled for any font/DPI change (``rescale_geometry``) and
+    clamped to the current screen (``clamp_geometry``). Returns ``None``
+    when nothing usable is saved, so callers keep the default placement.
+    """
+    if not geom_map:
+        return None
+    saved = geom_map.get(signature) or geom_map.get("legacy", "")
+    if not saved:
+        return None
+    geom = rescale_geometry(saved, saved_cw, current_cw)
+    return clamp_geometry(geom, screen_w, screen_h, min_w=min_w, min_h=min_h)
+
+
+@dataclass(frozen=True)
+class FontMetrics:
+    """Snapshot of derived font metrics. Cheap to recompute, immutable."""
+    cw: int            # char width — TkDefaultFont.measure("0")
+    lh: int            # line height — TkDefaultFont.metrics("linespace")
+    em: int            # alias for cw, exposed for readability in spacing code
+    row_height: int    # treeview row height (max(24, int(lh * 1.25)))
+    bold_font: tkfont.Font  # body font with weight=bold
+
+
+def setup_fonts(root: tk.Misc, *, body_pt: int = 10, code_pt: int = 10) -> None:
+    """Configure the six standard Tk named fonts with role-aware sizes.
+
+    Sets:
+      TkDefaultFont / TkTextFont / TkMenuFont = body_pt
+      TkHeadingFont                          = body_pt + 2, bold
+      TkTooltipFont                          = body_pt - 1
+      TkFixedFont                            = code_pt
+
+    All sizes are POINTS (positive numbers), so tk scaling DPI-scales them.
+
+    Idempotent: safe to call again to restyle the whole UI at runtime.
+    """
+    # body / text / menu — same size, regular weight
+    for name in ("TkDefaultFont", "TkTextFont", "TkMenuFont"):
+        try:
+            font = tkfont.nametofont(name)
+            font.configure(size=body_pt, weight="normal")
+        except tk.TclError:
+            pass
+
+    # heading — one point larger, bold. Bold weight already reads as a
+    # heading next to the regular body; +2 looked oversized on Windows
+    # (esp. the "Input sources" / "File outputs" section labels), so +1 is
+    # enough lift without dominating the surrounding sv_ttk widgets.
+    try:
+        heading = tkfont.nametofont("TkHeadingFont")
+        heading.configure(size=body_pt + 1, weight="bold")
+    except tk.TclError:
+        pass
+
+    # tooltip — one point smaller, regular
+    try:
+        tip = tkfont.nametofont("TkTooltipFont")
+        tip.configure(size=max(body_pt - 1, 6), weight="normal")
+    except tk.TclError:
+        pass
+
+    # monospace / code
+    try:
+        fixed = tkfont.nametofont("TkFixedFont")
+        # keep the platform-default family; only override size
+        fixed.configure(size=code_pt)
+    except tk.TclError:
+        pass
+
+
+def monitor_dpi(widget: tk.Misc) -> float:
+    """Return the current monitor's effective DPI as Tk sees it.
+
+    ``winfo_fpixels('1i')`` returns the pixels-per-inch Tk uses for sizing
+    fonts and ttk widgets; it reflects the current value of ``tk scaling``,
+    not the OS DPI on the monitor the window happens to be on. Wrapping it
+    keeps callers from sprinkling magic strings.
+
+    Note: for a true per-monitor DPI on Windows, the code path would be
+    Win32 ``MonitorFromWindow`` + ``GetDpiForMonitor``; that is out of
+    scope here. Users can set ``FLEXTOOL_DPI=...`` at startup as an
+    override when auto-detection picks the wrong monitor.
+    """
+    try:
+        return float(widget.tk.call("winfo", "fpixels", widget._w, "1i"))
+    except (tk.TclError, AttributeError):
+        return 96.0
+
+
+def get_metrics(root: tk.Misc | None = None) -> FontMetrics:
+    """Compute current font metrics from TkDefaultFont. Safe to call any time."""
+    default = tkfont.nametofont("TkDefaultFont")
+    cw = default.measure("0")
+    lh = default.metrics("linespace")
+    bold = default.copy()
+    bold.configure(weight="bold")
+    # Treeview row height must track the font the tree ACTUALLY renders cell
+    # text with — under sv_ttk that's SunValleyBodyFont, whose linespace runs
+    # ~20% tighter than TkDefaultFont's at the same visual size. Deriving the
+    # row height from TkDefaultFont (the old code) over-padded every row, so
+    # rows looked sparse at all DPIs. A flat 1.3× of the real linespace gives
+    # a comfortable click target without the gaps; the old max(24, …) px floor
+    # is dropped because a fixed pixel doesn't scale and only inflated rows at
+    # 96 DPI.
+    tree_lh = lh
+    try:
+        import tkinter.ttk as ttk
+        # lookup() returns a Tcl_Obj, not a str; str() yields the clean font
+        # name ("SunValleyBodyFont"), whereas passing the Tcl_Obj straight to
+        # nametofont raises "named font … does not already exist".
+        tree_font_name = str(ttk.Style().lookup("Treeview", "font") or "")
+        if tree_font_name:
+            tree_lh = tkfont.nametofont(tree_font_name).metrics("linespace")
+    except (tk.TclError, RuntimeError):
+        pass
+    return FontMetrics(
+        cw=cw,
+        lh=lh,
+        em=cw,
+        row_height=max(18, round(tree_lh * 1.3)),
+        bold_font=bold,
+    )

flextool/input_derivation/__init__.py

@@ -0,0 +1,281 @@
+"""SpineDBBackend output → :class:`FlexDataProvider`.
+
+The :mod:`input_derivation` tier sits between
+:mod:`flextool.spinedb_backend` (raw EAV → polars materialisation) and
+the in-cascade :class:`flextool.engine_polars._flex_data_provider.FlexDataProvider`
+that the rest of the engine consumes.
+
+Architecture
+------------
+
+::
+
+    SpineDB → SpineDBBackend → input_derivation → FlexDataProvider → cascade
+
+A derivation in this package reads its raw inputs **through the
+:class:`SpineDBBackend`** (or, for derivations that compose other
+derivation outputs, the Provider) and emits one or more canonical-
+schema :class:`polars.DataFrame` objects to the Provider via
+``provider.put(key, frame)``.
+
+**No disk writes.**  The derivation tier is purely in-memory; CSV
+emission is the Provider's job (``snapshot_processed_inputs`` /
+``--csv-dump``).
+
+Hard rules
+----------
+
+* No disk writes anywhere in this package.
+* No disk-fallback reads.  ``provider`` and ``backend`` are required
+  keyword arguments; the derivation fails loudly if either is missing.
+* Each derivation populates the Provider via ``provider.put(...)``;
+  return values are reserved for derivation-internal carriers (e.g.
+  ``ct_method_overrides`` from DC power flow, consumed by process
+  method).
+"""
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import spinedb_api as api
+from spinedb_api import DatabaseMapping
+
+if TYPE_CHECKING:
+    from flextool.engine_polars._flex_data_provider import FlexDataProvider
+
+
+__all__ = ["run"]
+
+
+def _provider_key(filename: str) -> str:
+    """Canonical Provider key for ``input/<stem>.csv`` style paths.
+
+    Matches the convention in :mod:`flextool.engine_polars._emit_provider_io`:
+    ``"<parent_dir_name>/<stem>"``.
+    """
+    p = Path(filename)
+    return f"{p.parent.name}/{p.stem}" if p.parent.name else p.stem
+
+
+def run(
+    backend_or_db_url,
+    provider: "FlexDataProvider",
+    logger: "logging.Logger | None" = None,
+    *,
+    scenario_name: "str | None" = None,
+    work_folder: "Path | None" = None,
+    precision_digits: int = 0,
+    memory_recorder=None,
+) -> None:
+    """Populate *provider* with the canonical ``input/`` + derivation
+    frames produced from the Spine database.
+
+    Pipeline
+    --------
+
+    1. **SpineDBBackend spec loops** — three loops over the canonical
+       spec lists (``_DEFAULT_VALUES_SPECS``, ``_ENTITY_SPECS``,
+       ``_PARAMETER_SPECS``) materialise ~120 EAV frames into the
+       Provider under their canonical ``input/<stem>`` key.
+    2. **Validators** (timeline timestep duration, ladder methods,
+       capacity margin storage exclusion, group output memberships).
+    3. **DB-driven derivations** (DC power flow, process method,
+       commodity ladder cumulative + annual + sets).
+    4. **Native preprocessing emitters** — the dozen modules under
+       :mod:`flextool.engine_polars._emit_*` that produce the
+       ``solve_data/*.csv`` artefacts the cascade consumes pre-solve.
+       Each is invoked directly with ``provider=`` so its frames flow
+       into the Provider and disk emission is skipped.
+
+    Parameters
+    ----------
+    backend_or_db_url
+        Either a Spine DB URL string (``sqlite:///...``) or a
+        pre-constructed :class:`SpineDBBackend`.  The URL form opens an
+        ephemeral DatabaseMapping for the duration of the call.
+    provider
+        Cascade-input :class:`FlexDataProvider`.  All frames land here.
+    logger
+        Optional logger.  Defaults to ``logging.getLogger(__name__)``.
+    scenario_name
+        Scenario filter applied to the DB mapping.  ``None`` runs
+        without a filter.
+    work_folder
+        Workdir for the (still-disk) batches that have not yet been
+        ported to Provider-only operation.  When ``None`` defaults to
+        :func:`pathlib.Path.cwd`.  Becomes optional in a later step
+        once every writer is Provider-only.
+    precision_digits
+        Float precision forwarded to ``SpineDBBackend.parameter_values``.
+    """
+    from flextool.spinedb_backend import SpineDBBackend
+    from flextool.input_derivation._specs import (
+        _ENTITY_SPECS,
+        _PARAMETER_SPECS,
+        _DEFAULT_VALUES_SPECS,
+    )
+    from flextool.input_derivation._validators import (
+        validate_timeline_timestep_duration,
+        validate_ladder_methods,
+        validate_group_output_memberships,
+        validate_capacity_margin_groups,
+        validate_connection_node_memberships,
+    )
+    from flextool.input_derivation._dc_power_flow import derive_dc_power_flow
+    from flextool.input_derivation._process_method import derive_process_method
+    from flextool.input_derivation._commodity_ladder import (
+        derive_commodity_ladder_cumulative,
+        derive_commodity_ladder_annual,
+    )
+    from flextool.input_derivation._commodity_ladder_sets import (
+        derive_commodity_ladder_sets,
+    )
+
+    if logger is None:
+        logger = logging.getLogger(__name__)
+    if provider is None:
+        raise TypeError("input_derivation.run requires a FlexDataProvider")
+
+    def _mem(label: str, user_label: str) -> None:
+        """Emit a phase checkpoint when a recorder was supplied; no-op
+        otherwise.  Lets the user follow input-pipeline phase progress
+        with section-delta accounting matching the cascade/build
+        checkpoints emitted by :mod:`_orchestration`.
+
+        The recorder's log lines are user-visible by default; full
+        tracemalloc-peak diagnostics and CSV emission are opt-in via
+        ``FLEXTOOL_MEMORY_DIAGNOSTICS=1`` (handled inside the recorder).
+        """
+        if memory_recorder is not None:
+            memory_recorder.checkpoint(label, logger, user_label=user_label)
+
+    wf = work_folder if work_folder is not None else Path.cwd()
+
+    def _do(db) -> None:
+        # Step 1 — SpineDBBackend spec loops.
+        backend = SpineDBBackend.__new__(SpineDBBackend)
+        backend._db = db                              # type: ignore[attr-defined]
+        backend._api = api                            # type: ignore[attr-defined]
+        backend._precision_digits = precision_digits  # type: ignore[attr-defined]
+        backend._scenario_name = scenario_name        # type: ignore[attr-defined]
+
+        for spec in _DEFAULT_VALUES_SPECS:
+            frame = backend.parameter_defaults(
+                cl_pars=spec["cl_pars"],
+                header=spec["header"],
+                filter_in_type=spec.get("filter_in_type"),
+                only_value=spec.get("only_value", False),
+            )
+            provider.put(_provider_key(spec["filename"]), frame)
+
+        for spec in _ENTITY_SPECS:
+            frame = backend.entities(
+                classes=spec.classes,
+                header=spec.header,
+                entity_dimens=spec.entity_dimens,
+            )
+            provider.put(_provider_key(spec.filename), frame)
+
+        validate_timeline_timestep_duration(db)
+
+        for spec in _PARAMETER_SPECS:
+            kwargs = {k: v for k, v in spec.items() if k != "filename"}
+            frame = backend.parameter_values(**kwargs)
+            provider.put(_provider_key(spec["filename"]), frame)
+        _mem("spine_db_read_end", "Spine DB loaded")
+
+        # Step 2 — DB-driven derivations.
+        ct_method_overrides = derive_dc_power_flow(backend, provider, logger)
+        derive_process_method(
+            backend, provider, logger,
+            ct_method_overrides=ct_method_overrides,
+        )
+        validate_ladder_methods(db, logger)
+        derive_commodity_ladder_cumulative(backend, provider, logger)
+        derive_commodity_ladder_annual(backend, provider, logger)
+        derive_commodity_ladder_sets(backend, provider)
+        _mem("db_derivations_end", "DB-driven derivations done")
+
+        # Step 3 — write_input-time native preprocessing emitters.
+        # Each emit_* threads the Provider directly so frames flow into
+        # memory rather than disk.
+        from flextool.engine_polars import (
+            _emit_leaf_sets as _leaf,
+            _emit_mid_sets as _mid,
+            _emit_calc_params as _calc,
+            _emit_arc_unions as _arc,
+            _emit_dispatchers as _disp,
+        )
+        input_dir = wf / "input"
+        solve_data_dir = wf / "solve_data"
+        os.makedirs(solve_data_dir, exist_ok=True)
+        _leaf.emit_period_param_sets(input_dir, solve_data_dir, provider=provider)
+        _leaf.emit_invest_method_sets(input_dir, solve_data_dir, provider=provider)
+        _leaf.emit_co2_method_sets(input_dir, solve_data_dir, provider=provider)
+        _leaf.emit_optional_yes(input_dir, solve_data_dir, provider=provider)
+        _leaf.emit_reserve_upDown_group(input_dir, solve_data_dir, provider=provider)
+        _leaf.emit_group_loss_share(input_dir, solve_data_dir, provider=provider)
+        _mid.emit_node_type_sets(input_dir, solve_data_dir, provider=provider)
+        _mid.emit_entity_lifetime_method(input_dir, solve_data_dir, provider=provider)
+        _mid.emit_process_ct_method(input_dir, solve_data_dir, provider=provider)
+        _mid.emit_process_startup_method(input_dir, solve_data_dir, provider=provider)
+        _mid.emit_node_inflow_method(input_dir, solve_data_dir, provider=provider)
+        _mid.emit_node_storage_binding_method(input_dir, solve_data_dir, provider=provider)
+        _mid.emit_node_penalty_method(input_dir, solve_data_dir, provider=provider)
+        _mid.emit_process_group_inside_group_nonsync(input_dir, solve_data_dir, provider=provider)
+        _mid.emit_process__sink_nonSync(input_dir, solve_data_dir, provider=provider)
+        _mid.emit_group_entity(input_dir, solve_data_dir, provider=provider)
+        _mid.emit_process_delayed__duration(input_dir, solve_data_dir, provider=provider)
+        _calc.emit_entity_total_caps(input_dir, solve_data_dir, provider=provider)
+        _calc.emit_process_method_projections(input_dir, provider=provider)
+        _calc.emit_process_VRE(input_dir, provider=provider)
+        _calc.emit_process_arc_method_joins(input_dir, provider=provider)
+        _calc.emit_process_profile_method_joins(input_dir, provider=provider)
+        _mid.emit_reserve_partitions(input_dir, solve_data_dir, provider=provider)
+        _mid.emit_commodity_node_co2(input_dir, solve_data_dir, provider=provider)
+        _mid.emit_process_coeff_zero_sets(input_dir, solve_data_dir, provider=provider)
+        _leaf.emit_def_optional_yes(input_dir, solve_data_dir, provider=provider)
+        _leaf.emit_process_delayed(input_dir, solve_data_dir, provider=provider)
+        _leaf.emit_simple_setof_projections(input_dir, solve_data_dir, provider=provider)
+        # emit_period_solve depends on solve_data outputs from
+        # emit_simple_setof_projections, so must run after.
+        _leaf.emit_period_solve(solve_data_dir, provider=provider)
+        _leaf.emit_time_set(input_dir, solve_data_dir, provider=provider)
+        _leaf.emit_enable_optional_outputs(solve_data_dir, provider=provider)
+        _leaf.emit_node_state_subsets(solve_data_dir, provider=provider)
+        _mid.emit_invest_total_sets(input_dir, solve_data_dir, provider=provider)
+        _mid.emit_ci_ladder_cumulative(input_dir, solve_data_dir, provider=provider)
+        _disp.emit_process_arc_unions(input_dir, solve_data_dir, provider=provider)
+        _arc.emit_param_in_use_sets(input_dir, solve_data_dir, provider=provider)
+
+        _mem("preprocessing_writers_end", "Preprocessing writers done")
+
+        # Step 4 — validators that need DB access.
+        validate_capacity_margin_groups(db, logger)
+        validate_group_output_memberships(db, logger)
+        validate_connection_node_memberships(db, logger)
+
+    # Accept either a backend, a DatabaseMapping or a URL string.
+    if isinstance(backend_or_db_url, str):
+        scen_config = (
+            api.filters.scenario_filter.scenario_filter_config(scenario_name)
+            if scenario_name else None
+        )
+        with DatabaseMapping(backend_or_db_url) as db:
+            # Hot-load the DB: fetching upfront is faster than repeated
+            # parameter_value lookups.
+            db.fetch_all("entity")
+            db.fetch_all("parameter_value")
+            if scen_config is not None:
+                api.filters.scenario_filter.scenario_filter_from_dict(db, scen_config)
+            os.makedirs(wf / "input", exist_ok=True)
+            _do(db)
+    else:
+        # Accept a SpineDBBackend (with ._db) or a DatabaseMapping
+        # directly; both expose the find_* API we need.
+        db = getattr(backend_or_db_url, "_db", backend_or_db_url)
+        os.makedirs(wf / "input", exist_ok=True)
+        _do(db)