flextool 4.0.0__py3-none-any.whl

flextool/process_outputs/write_spinedb.py

@@ -0,0 +1,1267 @@
+"""Write FlexTool processed results into a SpineDB (the ``spinedb`` output
+write-method).
+
+This module dumps the engine's in-memory ``results`` dict of pandas
+DataFrames (built in :mod:`flextool.process_outputs.write_outputs`) into a
+SpineDB that uses the FlexTool **results schema**
+(``flextool/schemas/spinedb_results_schema.json``).  Multiple runs coexist
+in one DB, separated by Spine **alternatives** (one alternative per
+scenario; multiple solves coexist inside the ``solve`` Map axis).
+
+Schema note: the results schema JSON was generated by trimming the three
+duplicate reserve entity classes (``unit__reserve__upDown__node.1/.2/.3``)
+from the legacy results template — they carry no parameter definitions and
+nothing references them.  The trimmed schema has 12 entity classes and 58
+parameter definitions.
+
+Key correctness facts (verified against the engine code, 2026-06-03):
+
+* The ``results`` dict keys are the RAW engine table names (e.g.
+  ``unit_outputNode_dt_ee``), NOT renamed display names.
+* ``import_data`` does NOT auto-create relationship member entities, so the
+  writer explicitly emits every member element entity (each ``unit``,
+  ``node``, ``connection``, ``group``, ``reserve``, ``upDown``, plus the
+  literal ``model``-class entities ``"cost"`` and ``"model"``) in addition
+  to the relationship entities.
+* Capacity Map keys stay ``existing``/``invested``/``divested``/``total``
+  (no ``retired`` rename).
+* Discount-factor params (#33/#34) derive from
+  ``par.inflation_factor_investment_yearly`` /
+  ``par.inflation_factor_operations_yearly``.  ``par`` is threaded in as an
+  optional keyword; when absent those two params are skipped.
+* Empty / all-NaN cells emit nothing (no empty Maps, no spurious 0).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import math
+import os
+import re
+from typing import Any
+
+import pandas as pd
+from spinedb_api import DatabaseMapping, import_data
+from spinedb_api.parameter_value import Map
+
+from flextool.process_outputs._output_meta import FACTOR, result_key_summary
+
+logger = logging.getLogger(__name__)
+
+_SCHEMA_PATH = os.path.join(
+    os.path.dirname(os.path.dirname(__file__)),
+    "schemas",
+    "spinedb_results_schema.json",
+)
+
+
+# ---------------------------------------------------------------------------
+# Whitelist: raw engine table name -> spec.
+#
+# spec fields:
+#   ec          : target entity class name
+#   param       : target parameter definition name
+#   entity_dims : number of leading column levels that form the entity byname
+#                 (after reordering to schema dim order).  0 means a literal
+#                 fixed entity (see ``fixed_entity``).
+#   fixed_entity: literal byname tuple to use when entity_dims == 0
+#                 (cost params: "cost" / "model").
+#   has_time    : True for timestep (_dt) frames -> Map [solve]->period->time;
+#                 False for period (_d) frames -> Map [solve]->period.
+#   category    : how to treat the remaining (non-entity) column levels:
+#                   None      -> single value column, no category nesting
+#                   "header"  -> remaining column levels become the OUTERMOST
+#                                Map keys (matching importer position:"header")
+#   reserve_filter: 'unit' or 'connection' -> route rows whose process column
+#                   is a unit / connection respectively.
+#   topology    : 'connection_triple' -> column is a single connection name;
+#                 reconstruct the (connection, node, node) byname from
+#                 ``s.process_source_sink``.
+# ---------------------------------------------------------------------------
+
+SPINEDB_OUTPUT_SPEC: dict[str, dict[str, Any]] = {
+    # --- node -------------------------------------------------------------
+    "node_dt_ep": dict(ec="node", param="balance_t", entity_dims=1,
+                       has_time=True, category="header"),
+    "node_d_ep": dict(ec="node", param="balance", entity_dims=1,
+                      has_time=False, category="header"),
+    "node_state_dt_e": dict(ec="node", param="state_t", entity_dims=1,
+                            has_time=True, category=None),
+    "node_prices_dt_e": dict(ec="node", param="price_t", entity_dims=1,
+                             has_time=True, category=None),
+    "node_capacity_ed_p": dict(ec="node", param="capacity", entity_dims=1,
+                               has_time=False, category="header",
+                               entity_index="node"),
+    "dual_invest_effective_node_d_e": dict(ec="node", param="invest_marginal",
+                                           entity_dims=1, has_time=False,
+                                           category=None),
+    # --- unit -------------------------------------------------------------
+    "unit_online_dt_e": dict(ec="unit", param="online_t", entity_dims=1,
+                             has_time=True, category=None, entity_filter="unit"),
+    "unit_online_average_d_e": dict(ec="unit", param="online_average",
+                                    entity_dims=1, has_time=False,
+                                    category=None, entity_filter="unit"),
+    "unit_startup_d_e": dict(ec="unit", param="startup_cumulative",
+                             entity_dims=1, has_time=False, category=None,
+                             entity_filter="unit"),
+    "unit_capacity_ed_p": dict(ec="unit", param="capacity", entity_dims=1,
+                               has_time=False, category="header",
+                               entity_index="unit"),
+    "dual_invest_effective_unit_d_e": dict(ec="unit", param="invest_marginal",
+                                           entity_dims=1, has_time=False,
+                                           category=None),
+    "process_co2_d_eee": dict(ec="unit", param="CO2_annualized",
+                              entity_dims=1, has_time=False, category="header",
+                              co2_type="unit"),
+    # --- unit__node -------------------------------------------------------
+    "unit_outputNode_dt_ee": dict(ec="unit__node", param="flow_t",
+                                  entity_dims=2, has_time=True, category=None),
+    "unit_inputNode_dt_ee": dict(ec="unit__node", param="flow_t",
+                                 entity_dims=2, has_time=True, category=None),
+    "unit_outputNode_d_ee": dict(ec="unit__node", param="flow_annualized",
+                                 entity_dims=2, has_time=False, category=None),
+    "unit_inputNode_d_ee": dict(ec="unit__node", param="flow_annualized",
+                                entity_dims=2, has_time=False, category=None),
+    "unit_ramp_outputs_dt_ee": dict(ec="unit__node", param="ramp_t",
+                                    entity_dims=2, has_time=True, category=None),
+    "unit_ramp_inputs_dt_ee": dict(ec="unit__node", param="ramp_t",
+                                   entity_dims=2, has_time=True, category=None),
+    "unit_outputs_cf_d_ee": dict(ec="unit__node", param="cf", entity_dims=2,
+                                 has_time=False, category=None),
+    "unit_inputs_cf_d_ee": dict(ec="unit__node", param="cf", entity_dims=2,
+                                has_time=False, category=None),
+    "unit_curtailment_outputNode_dt_ee": dict(ec="unit__node",
+                                              param="curtailment_t",
+                                              entity_dims=2, has_time=True,
+                                              category=None),
+    "unit_curtailment_share_outputNode_d_ee": dict(ec="unit__node",
+                                                   param="curtailment_share",
+                                                   entity_dims=2,
+                                                   has_time=False,
+                                                   category=None),
+    # --- connection__node__node ------------------------------------------
+    "connection_dt_eee": dict(ec="connection__node__node", param="flow_t",
+                              entity_dims=1, has_time=True, category=None,
+                              topology="connection_triple"),
+    "connection_d_eee": dict(ec="connection__node__node",
+                             param="flow_annualized", entity_dims=1,
+                             has_time=False, category=None,
+                             topology="connection_triple"),
+    "connection_leftward_dt_eee": dict(ec="connection__node__node",
+                                       param="flow_to_first_node_t",
+                                       entity_dims=1, has_time=True,
+                                       category=None,
+                                       topology="connection_triple"),
+    "connection_leftward_d_eee": dict(ec="connection__node__node",
+                                      param="flow_to_first_node_annualized",
+                                      entity_dims=1, has_time=False,
+                                      category=None,
+                                      topology="connection_triple"),
+    "connection_rightward_dt_eee": dict(ec="connection__node__node",
+                                        param="flow_to_second_node_t",
+                                        entity_dims=1, has_time=True,
+                                        category=None,
+                                        topology="connection_triple"),
+    "connection_rightward_d_eee": dict(ec="connection__node__node",
+                                       param="flow_to_second_node_annualized",
+                                       entity_dims=1, has_time=False,
+                                       category=None,
+                                       topology="connection_triple"),
+    "connection_cf_d_e": dict(ec="connection__node__node", param="cf",
+                              entity_dims=1, has_time=False, category=None,
+                              topology="connection_triple"),
+    # --- connection -------------------------------------------------------
+    "connection_capacity_ed_p": dict(ec="connection", param="capacity",
+                                     entity_dims=1, has_time=False,
+                                     category="header",
+                                     entity_index="connection"),
+    "dual_invest_effective_connection_d_e": dict(ec="connection",
+                                                 param="invest_marginal",
+                                                 entity_dims=1, has_time=False,
+                                                 category=None),
+    # --- per-entity cost break-down (period level, category in columns) ---
+    # Entity is an INDEX level (named unit/connection/node) and columns are
+    # cost categories — same shape as the capacity tables, so they route
+    # through the entity_index serializer.
+    "cost_unit_annualized_d_ec": dict(ec="unit", param="cost_annualized",
+                                      entity_dims=1, has_time=False,
+                                      category="header", entity_index="unit"),
+    "cost_unit_discounted_d_ec": dict(ec="unit", param="cost_discounted",
+                                      entity_dims=1, has_time=False,
+                                      category="header", entity_index="unit"),
+    "cost_connection_annualized_d_ec": dict(ec="connection",
+                                            param="cost_annualized",
+                                            entity_dims=1, has_time=False,
+                                            category="header",
+                                            entity_index="connection"),
+    "cost_connection_discounted_d_ec": dict(ec="connection",
+                                            param="cost_discounted",
+                                            entity_dims=1, has_time=False,
+                                            category="header",
+                                            entity_index="connection"),
+    "cost_node_annualized_d_ec": dict(ec="node", param="cost_annualized",
+                                      entity_dims=1, has_time=False,
+                                      category="header", entity_index="node"),
+    "cost_node_discounted_d_ec": dict(ec="node", param="cost_discounted",
+                                      entity_dims=1, has_time=False,
+                                      category="header", entity_index="node"),
+    # --- model (cost) -----------------------------------------------------
+    "costs_dt_p": dict(ec="model", param="cost_t", entity_dims=0,
+                       fixed_entity=("cost",), has_time=True,
+                       category="header"),
+    "annualized_costs_d_p": dict(ec="model", param="cost_annualized",
+                                 entity_dims=0, fixed_entity=("cost",),
+                                 has_time=False, category="header"),
+    "costs_discounted_d_p": dict(ec="model", param="cost_discounted_solve",
+                                 entity_dims=0, fixed_entity=("model",),
+                                 has_time=False, category="header",
+                                 collapse_solve=True),
+    "costs_discounted_p_": dict(ec="model", param="cost_discounted_total",
+                                entity_dims=0, fixed_entity=("model",),
+                                has_time=False, category="header",
+                                series_category=True),
+    # --- group ------------------------------------------------------------
+    "nodeGroup_flows_dt_g": dict(ec="group", param="flow_t", entity_dims=1,
+                                 has_time=True, category=None),
+    "nodeGroup_flows_d_g": dict(ec="group", param="flow_annualized",
+                                entity_dims=1, has_time=False, category=None),
+    "nodeGroup_flows_dt_gpe": dict(ec="group", param="sum_flow_t",
+                                   entity_dims=1, has_time=True,
+                                   category="header"),
+    "nodeGroup_flows_d_gpe": dict(ec="group", param="sum_flow_annualized",
+                                  entity_dims=1, has_time=False,
+                                  category="header"),
+    "nodeGroup_gd_p": dict(ec="group", param="indicator", entity_dims=1,
+                           has_time=False, category="header",
+                           entity_index="group"),
+    "nodeGroup_VRE_share_dt_g": dict(ec="group", param="VRE_share_t",
+                                     entity_dims=1, has_time=True,
+                                     category=None),
+    "CO2_d_g": dict(ec="group", param="CO2_annualized", entity_dims=1,
+                    has_time=False, category=None),
+    "nodeGroup_inertia_dt_g": dict(ec="group", param="inertia_t",
+                                   entity_dims=1, has_time=True,
+                                   category=None),
+    "nodeGroup_inertia_largest_flow_dt_g": dict(ec="group",
+                                                param="inertia_largest_flow_t",
+                                                entity_dims=1, has_time=True,
+                                                category=None),
+    "nodeGroup_unit_node_inertia_dt_gee": dict(ec="group",
+                                               param="inertia_unit_node_t",
+                                               entity_dims=1, has_time=True,
+                                               category="header"),
+    "nodeGroup_slack_capacity_margin_d_g": dict(ec="group",
+                                                param="slack_capacity_margin",
+                                                entity_dims=1, has_time=False,
+                                                category=None),
+    "nodeGroup_slack_inertia_dt_g": dict(ec="group", param="slack_inertia_t",
+                                         entity_dims=1, has_time=True,
+                                         category=None),
+    "nodeGroup_slack_nonsync_dt_g": dict(ec="group", param="slack_nonsync_t",
+                                         entity_dims=1, has_time=True,
+                                         category=None),
+    # --- group__reserve__upDown ------------------------------------------
+    "nodeGroup_slack_reserve_dt_eeg": dict(ec="group__reserve__upDown",
+                                           param="slack_reserve_t",
+                                           entity_dims=3, has_time=True,
+                                           category=None),
+    # --- unit/connection__reserve__upDown__node --------------------------
+    "process_reserve_upDown_node_dt_eppe": dict(
+        ec="unit__reserve__upDown__node", param="reservation_t",
+        entity_dims=4, has_time=True, category=None, reserve_split=True),
+    "process_reserve_average_d_eppe": dict(
+        ec="unit__reserve__upDown__node", param="reservation_average",
+        entity_dims=4, has_time=False, category=None, reserve_split=True),
+}
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def derive_alternative_name(scenario_name: str, solve_name: str) -> str:
+    """Return the Spine alternative name for a run.
+
+    v1: deterministically returns ``scenario_name`` (no timestamp / random,
+    honoring cross-process determinism).  Multiple solves coexist inside the
+    ``solve`` Map axis of each value; multiple runs coexist as distinct
+    alternatives.  A future ``--results-alternative`` override hooks here.
+    """
+    return scenario_name
+
+
+def ensure_results_db(db_url: str) -> None:
+    """Create the results DB from the schema JSON if it is absent; no-op if
+    it already exists.
+
+    The schema JSON is fed straight to ``import_data`` (its top-level keys
+    ``entity_classes`` / ``parameter_definitions`` / ``alternatives`` are
+    valid ``import_data`` kwargs).  ``import_data`` of classes/params is
+    idempotent, so re-running against an existing DB would be harmless, but
+    we short-circuit on an existing sqlite file for speed.
+
+    Concurrency contract (the Toolbox re-create context launches parallel
+    scenario iterations into ONE shared ``results.sqlite``):
+
+    * **Creation serializes via a sidecar lock.**  For ``sqlite:///`` targets
+      the create-if-absent is guarded by an exclusive sidecar lock on
+      ``<db>.lock`` (``fcntl.flock`` on POSIX, ``msvcrt.locking`` on
+      Windows), so exactly ONE process
+      ever builds the schema.  Inside the lock we re-check for the target and,
+      if another process already created it, discard our temp build and NEVER
+      ``os.replace`` over it — so a late rename can never clobber a DB another
+      process has already begun importing into.  The schema is built into a
+      unique temp file in the target directory and ``os.replace``-d into place
+      (atomic on the same filesystem) only when the target is still absent.
+    * **Subsequent per-process IMPORTs append and serialize via the sqlite
+      busy-timeout.**  Each scenario writes its own alternative through
+      ``write_spinedb`` -> ``import_data``; concurrent appends to the shared
+      sqlite file are serialized by spinedb_api's connection busy-timeout —
+      ``DatabaseMapping.create_engine`` passes ``connect_args={"timeout":
+      sqlite_timeout}`` (default 1800 s), the pysqlite busy-timeout, so a
+      writer that finds the DB locked WAITS and retries rather than failing
+      with ``SQLITE_BUSY``.  We therefore do NOT hold the creation lock across
+      the import — appends are independent writers and only the cold-start
+      create must be single-writer.
+
+    Non-sqlite URLs (e.g. a shared server) fall back to the direct in-place
+    create (no atomic rename / file lock possible across a network DSN).
+    """
+    if db_url.startswith("sqlite:///"):
+        path = db_url[len("sqlite:///"):]
+        # A present DB may still lag the current schema (additive params /
+        # classes shipped after it was built).  Bring it up to date without
+        # taking the cold-start lock in the steady state.
+        if os.path.exists(path):
+            _top_up_schema_if_stale(db_url)
+            return
+        _ensure_results_db_atomic(db_url, path)
+        return
+    # Non-sqlite target: cannot atomically rename; create in place.
+    _import_schema(db_url)
+
+
+def _required_schema_sets() -> tuple[set[str], set[tuple[str, str]]]:
+    """The full set of entity-class names and ``(entity_class, param)`` pairs
+    the current results schema requires, read from the schema JSON."""
+    with open(_SCHEMA_PATH, encoding="utf-8") as fh:
+        schema = json.load(fh)
+    required_classes = {ec[0] for ec in schema["entity_classes"]}
+    required_params = {(pd[0], pd[1]) for pd in schema["parameter_definitions"]}
+    return required_classes, required_params
+
+
+def _top_up_schema_if_stale(db_url: str) -> None:
+    """Bring a pre-existing sqlite results DB up to the current schema.
+
+    An additive schema change (a new entity class or parameter definition)
+    never reaches a ``results.sqlite`` built by an older FlexTool: the
+    cold-start create short-circuits on the existing file, so a later
+    ``write_spinedb`` crashes when it references a param the DB lacks.  Detect
+    the gap with a **lock-free, read-only gate** and, only when the DB is
+    stale, import the missing schema keys **under the sidecar lock** so
+    concurrent callers converge on ONE top-up (no duplicate rows, no
+    UNIQUE-violation).
+    """
+    required_classes, required_params = _required_schema_sets()
+
+    # Gate: lock-free, read-only.  In the steady state (nothing missing) we
+    # never take the lock and never write.  The gate mapping MUST be closed
+    # before we take the lock: its item cache would otherwise go stale under
+    # another process's concurrent commit (critique BLOCKER #1).
+    with DatabaseMapping(db_url) as db:
+        have_classes = {c["name"] for c in db.get_entity_class_items()}
+        have_params = {(p["entity_class_name"], p["name"])
+                       for p in db.get_parameter_definition_items()}
+    missing_classes = required_classes - have_classes
+    missing_params = required_params - have_params
+    if not missing_classes and not missing_params:
+        return
+
+    # Stale path: serialize the top-up under the sidecar lock.
+    path = db_url[len("sqlite:///"):]
+    lock_path = path + ".lock"
+    with open(lock_path, "a") as lock_fh:
+        _lock_exclusive(lock_fh)
+        try:
+            # FRESH mapping under the lock (do NOT reuse the gate mapping — its
+            # cache is stale after another process's commit).  Re-read the
+            # have-sets: another process may already have topped up.
+            db = DatabaseMapping(db_url)
+            try:
+                have_classes = {c["name"]
+                                for c in db.get_entity_class_items()}
+                have_params = {(p["entity_class_name"], p["name"])
+                               for p in db.get_parameter_definition_items()}
+                still_missing = (required_classes - have_classes) or (
+                    required_params - have_params)
+                if not still_missing:
+                    return  # another process already topped up
+                with open(_SCHEMA_PATH, encoding="utf-8") as fh:
+                    schema = json.load(fh)
+                _apply_derived_descriptions(schema)
+                # Import ALL schema keys EXCEPT ``alternatives`` (never re-seed
+                # 'Base' or touch user run alternatives).  Derive the kwargs
+                # rather than hardcoding entity_classes/parameter_definitions,
+                # so any future value-list / superclass key is carried too.
+                # Re-importing existing entity classes merges on NAME
+                # harmlessly; a FUTURE *new* entity class carrying a hardcoded
+                # id in the schema JSON would need its id stripped here to
+                # avoid an id collision on this top-up path.
+                count, errors = import_data(
+                    db, **{k: v for k, v in schema.items()
+                           if k != "alternatives"})
+                if errors:
+                    raise RuntimeError(
+                        f"Failed to top up results schema: {len(errors)} "
+                        f"errors: {errors[:5]}"
+                    )
+                db.commit_session("Top-up results schema")
+                logger.debug("Topped up results DB schema (%d items)", count)
+            finally:
+                db.close()
+        finally:
+            _unlock(lock_fh)
+
+
+def _lock_exclusive(lock_fh) -> None:
+    """Acquire a blocking exclusive lock on an open file handle.
+
+    Portable across POSIX (``fcntl.flock``) and Windows (``msvcrt.locking``);
+    ``fcntl`` does not exist on Windows, so dispatch on what imports."""
+    try:
+        import fcntl
+    except ImportError:
+        import msvcrt
+        import time
+
+        # ``msvcrt.locking`` locks ``nbytes`` from the current file position;
+        # lock a single byte at offset 0.  Use the non-blocking variant in a
+        # retry loop so we block indefinitely rather than giving up after the
+        # ~10s LK_LOCK ceiling.
+        lock_fh.seek(0)
+        while True:
+            try:
+                msvcrt.locking(lock_fh.fileno(), msvcrt.LK_NBLCK, 1)
+                return
+            except OSError:
+                time.sleep(0.05)
+    else:
+        fcntl.flock(lock_fh.fileno(), fcntl.LOCK_EX)
+
+
+def _unlock(lock_fh) -> None:
+    """Release a lock taken by :func:`_lock_exclusive` (portable)."""
+    try:
+        import fcntl
+    except ImportError:
+        import msvcrt
+
+        lock_fh.seek(0)
+        try:
+            msvcrt.locking(lock_fh.fileno(), msvcrt.LK_UNLCK, 1)
+        except OSError:
+            pass
+    else:
+        fcntl.flock(lock_fh.fileno(), fcntl.LOCK_UN)
+
+
+def _replace_with_retry(src: str, dst: str, *, attempts: int = 20,
+                        delay: float = 0.05) -> None:
+    """``os.replace(src, dst)`` retrying transient Windows sharing errors.
+
+    On Windows a file that was just closed can stay briefly locked, so the
+    rename raises ``PermissionError`` (WinError 32).  POSIX never hits this,
+    so the first attempt always succeeds there."""
+    import time
+
+    for i in range(attempts):
+        try:
+            os.replace(src, dst)
+            return
+        except PermissionError:
+            if i == attempts - 1:
+                raise
+            time.sleep(delay)
+
+
+def _ensure_results_db_atomic(db_url: str, path: str) -> None:
+    """Create the schema DB at ``path`` if absent, safe under concurrent
+    cold-start callers writing the SAME shared results DB.
+
+    The create-if-absent is serialized by an exclusive lock on a sidecar
+    ``<db>.lock`` file (``fcntl.flock`` on POSIX, ``msvcrt.locking`` on
+    Windows): only the winner of the lock builds the schema.  Both the cheap
+    pre-check (in :func:`ensure_results_db`) and the re-check UNDER the lock
+    guard against ``os.replace`` clobbering a target another process has
+    already created (and may already be importing into) — the rename happens
+    only while the target is still absent."""
+    import uuid
+
+    target_dir = os.path.dirname(path) or "."
+    os.makedirs(target_dir, exist_ok=True)
+
+    lock_path = path + ".lock"
+    # The lock file persists (it is the rendez-vous point); only the lock is
+    # released.  Opened in append mode so concurrent opens never truncate it.
+    with open(lock_path, "a") as lock_fh:
+        _lock_exclusive(lock_fh)
+        try:
+            # Re-check UNDER the lock: another process may have created the
+            # target between our pre-check and acquiring the lock.  If so we
+            # must NOT build/rename — clobbering it could corrupt an import
+            # already in progress in that process.
+            if os.path.exists(path):
+                return
+            tmp_path = os.path.join(
+                target_dir, f".results-{uuid.uuid4().hex}.sqlite.tmp")
+            tmp_url = "sqlite:///" + tmp_path
+            try:
+                _import_schema(tmp_url)
+                # Still absent (we hold the lock, so it cannot appear now) —
+                # commit the build atomically.  Retry the rename briefly: on
+                # Windows a just-closed SQLite handle can linger a moment and
+                # ``os.replace`` raises ``PermissionError`` (WinError 32) until
+                # it is fully released.
+                _replace_with_retry(tmp_path, path)
+            finally:
+                # Discard the temp on any error mid-build.
+                if os.path.exists(tmp_path):
+                    try:
+                        os.remove(tmp_path)
+                    except OSError:
+                        pass
+        finally:
+            _unlock(lock_fh)
+
+
+# ---------------------------------------------------------------------------
+# Parameter-definition descriptions: prose from the schema, UNITS from code.
+#
+# The checked-in results schema carries rich, hand-written prose (per-category
+# breakdowns).  We keep that prose but make the **unit** authoritative from the
+# single source (``_output_meta``): at DB-create, for every param that maps to
+# a known transform, we replace the description's leading ``[unit]`` token with
+# the derived one and prepend it where missing.  Empty descriptions are filled
+# wholesale.  Params with no mapped transform (e.g. ``cf``) keep their
+# hand-written description untouched.  This makes unit drift structurally
+# impossible — the units are GENERATED into the schema, never compared against
+# it — so the old CI drift ratchet is retired.
+# ---------------------------------------------------------------------------
+
+# Leading unit token: ``[MW]``, ``[per unit]``, or the cost tables' ``M[CUR]``.
+_LEADING_UNIT_RE = re.compile(r"^\s*(?:M\s*\[[^\]]*\]|\[[^\]]*\])\s*")
+
+
+def _derived_param_meta() -> tuple[dict[tuple[str, str], tuple[str, str]],
+                                   dict[str, tuple[str, str]]]:
+    """Build derived ``(unit, short_text)`` keyed by ``(ec, param)`` and an
+    unambiguous-by-param fallback.
+
+    The ``(ec, param)`` map drives the exact class; the param-only fallback
+    covers classes absent from :data:`SPINEDB_OUTPUT_SPEC` that share a param
+    name with a documented one (e.g. the ``connection__reserve__*`` params),
+    but only when that param has a single distinct unit across all classes.
+    """
+    by_ecp: dict[tuple[str, str], tuple[str, str]] = {}
+    units_by_param: dict[str, set[str]] = {}
+    text_by_param: dict[str, tuple[str, str]] = {}
+    for table_name, spec in SPINEDB_OUTPUT_SPEC.items():
+        param = spec.get("param")
+        summary = result_key_summary(table_name)
+        if not param or summary is None:
+            continue
+        unit, _sem, tooltip = summary
+        if unit == "ratio":          # result_key_summary's unitless sentinel
+            unit = ""                # → renders as "[per unit]" via _unit_tag
+        by_ecp.setdefault((spec.get("ec"), param), (unit, tooltip))
+        units_by_param.setdefault(param, set()).add(unit)
+        text_by_param.setdefault(param, (unit, tooltip))
+    # Params sourced from ``par`` (not a results table): the two discount
+    # factors are dimensionless (FACTOR).
+    for p in ("investments discount factor", "operations discount factor"):
+        units_by_param.setdefault(p, {FACTOR.unit})
+        text_by_param.setdefault(p, (FACTOR.unit, FACTOR.tooltip))
+    unambiguous = {p: text_by_param[p]
+                   for p, us in units_by_param.items() if len(us) == 1}
+    return by_ecp, unambiguous
+
+
+def _unit_tag(unit: str) -> str:
+    """The bracketed unit token; unitless quantities render as ``[per unit]``."""
+    return f"[{unit}]" if unit else "[per unit]"
+
+
+def derived_param_unit_map() -> dict[tuple[str, str], str]:
+    """``{(entity_class, param): derived_unit}`` for params with a known
+    transform — the authoritative units merged into the schema."""
+    by_ecp, _unambiguous = _derived_param_meta()
+    return {key: unit for key, (unit, _text) in by_ecp.items()}
+
+
+def _apply_derived_descriptions(schema: dict) -> None:
+    """Merge derived units into ``parameter_definition`` descriptions.
+
+    Mutates ``schema['parameter_definitions']`` in place: an entry is
+    ``[entity_class, param, default, value_list, description, type]``.  For
+    every param with a derived unit, the leading unit token is replaced with
+    the derived one (prose preserved); empty descriptions are filled from the
+    derived short text.  Params without a derived unit are left untouched."""
+    by_ecp, unambiguous = _derived_param_meta()
+    for entry in schema.get("parameter_definitions", []):
+        ec, param, existing = entry[0], entry[1], entry[4]
+        derived = by_ecp.get((ec, param)) or unambiguous.get(param)
+        if not derived:
+            continue
+        unit, short_text = derived
+        prose = _LEADING_UNIT_RE.sub("", existing) if existing else short_text
+        entry[4] = f"{_unit_tag(unit)} {prose}".strip()
+
+
+def _import_schema(db_url: str) -> None:
+    """Load the results schema JSON into the DB at ``db_url`` (created if
+    needed).
+
+    Uses an explicit ``db.close()`` rather than the ``with DatabaseMapping``
+    context manager: ``__exit__`` only closes the *session*, leaving the
+    engine's connection pool holding the SQLite file open.  ``close()``
+    disposes the engine, releasing the handle.  This matters on Windows,
+    which refuses to ``os.replace`` a file with an open handle (POSIX has no
+    such restriction)."""
+    with open(_SCHEMA_PATH, encoding="utf-8") as fh:
+        schema = json.load(fh)
+    _apply_derived_descriptions(schema)
+    db = DatabaseMapping(db_url, create=True)
+    try:
+        count, errors = import_data(db, **schema)
+        if errors:
+            raise RuntimeError(
+                f"Failed to initialize results schema: {len(errors)} errors: "
+                f"{errors[:5]}"
+            )
+        db.commit_session("Initialized results schema")
+        logger.debug("Initialized results DB schema (%d items)", count)
+    finally:
+        db.close()
+
+
+def write_spinedb(results, s, db_url, scenario_name, solve_name,
+                  *, purge_alternative=True, par=None) -> int:
+    """Write the processed ``results`` into the SpineDB at ``db_url``.
+
+    Parameters
+    ----------
+    results : dict[str, pandas.DataFrame]
+        Processed results keyed by RAW engine table name.
+    s : object
+        The engine ``s`` (sets) namespace.  Used for solve reconstruction
+        (``solve_period_time`` / ``solve_period``), process partitioning
+        (``process_unit`` / ``process_connection``) and connection topology
+        (``process_source_sink``).
+    db_url : str
+        Target SpineDB URL (e.g. ``sqlite:///.../results.sqlite``).
+    scenario_name, solve_name : str
+        Run identifiers.  ``scenario_name`` becomes the alternative name;
+        ``solve_name`` is used as the ``solve`` Map key for frames whose
+        solve axis cannot be reconstructed per-row.
+    purge_alternative : bool, keyword-only, default True
+        Delete existing ``parameter_value`` items in the target alternative
+        before writing (so a re-run replaces rather than duplicates).
+    par : object, keyword-only, default None
+        The engine ``par`` (parameters) namespace.  Required only for the
+        two discount-factor params (#33/#34); when None those are skipped.
+
+    Returns
+    -------
+    int
+        The ``import_data`` count for the parameter-value write.
+    """
+    ensure_results_db(db_url)
+    alternative_name = derive_alternative_name(scenario_name, solve_name)
+
+    if purge_alternative:
+        _purge_alternative(db_url, alternative_name)
+
+    entities, parameter_values, entity_alternatives = collect_spinedb_payload(
+        results, s, alternative_name, solve_name, par=par,
+    )
+
+    with DatabaseMapping(db_url) as db:
+        count, errors = import_data(
+            db,
+            alternatives=[(alternative_name, f"FlexTool results: {alternative_name}")],
+            entities=entities,
+            parameter_values=parameter_values,
+            entity_alternatives=entity_alternatives,
+        )
+        if errors:
+            raise RuntimeError(
+                f"Failed to write results to {db_url}: {len(errors)} errors: "
+                f"{errors[:5]}"
+            )
+        db.commit_session(f"FlexTool results: {alternative_name}")
+
+    logger.debug(
+        "Wrote %d items to SpineDB alternative '%s' (%d entities, %d values)",
+        count, alternative_name, len(entities), len(parameter_values),
+    )
+    return count
+
+
+# ---------------------------------------------------------------------------
+# Payload collection
+# ---------------------------------------------------------------------------
+
+def collect_spinedb_payload(results, s, alternative_name, solve_name,
+                            *, par=None):
+    """Build the ``(entities, parameter_values, entity_alternatives)`` lists
+    for one run by iterating :data:`SPINEDB_OUTPUT_SPEC`.
+
+    Member element entities are collected explicitly (``import_data`` does
+    not auto-create them) and deduplicated.  Whitelist keys absent from
+    ``results`` (or empty / all-NaN) are skipped with a debug log.
+    """
+    entity_set: set[tuple[str, tuple]] = set()
+    parameter_values: list[tuple] = []
+
+    member_classes = _member_class_map(s)
+
+    for table_name, spec in SPINEDB_OUTPUT_SPEC.items():
+        if table_name not in results:
+            logger.debug("spinedb: table '%s' absent from results — skipped",
+                         table_name)
+            continue
+        df = results[table_name]
+        if df is None:
+            continue
+        if isinstance(df, pd.Series):
+            df = df.to_frame()
+        if isinstance(df, pd.DataFrame) and df.empty:
+            logger.debug("spinedb: table '%s' empty — skipped", table_name)
+            continue
+        try:
+            pvs = df_to_spine_maps(df, spec, s, solve_name, par=par,
+                                   alternative_name=alternative_name)
+        except Exception:
+            logger.exception(
+                "spinedb: failed to serialize table '%s' — skipped",
+                table_name)
+            continue
+        for ec, byname, value in pvs:
+            parameter_values.append(
+                (ec, byname, spec["param"], value, alternative_name))
+            entity_set.add((ec, byname))
+            # explicitly emit member element entities
+            for member in _member_entities(ec, byname, member_classes):
+                entity_set.add(member)
+
+    # Discount factors (#33 / #34) derive from par, not from results.
+    if par is not None:
+        for fam_attr, param_name in (
+            ("inflation_factor_investment_yearly", "investments discount factor"),
+            ("inflation_factor_operations_yearly", "operations discount factor"),
+        ):
+            value = _discount_factor_map(par, fam_attr, s, solve_name)
+            if value is not None:
+                parameter_values.append(
+                    ("model", ("model",), param_name, value, alternative_name))
+                entity_set.add(("model", ("model",)))
+    else:
+        logger.debug("spinedb: par is None — discount-factor params skipped")
+
+    entities = sorted(entity_set, key=lambda x: (x[0], x[1]))
+    entity_alternatives = [
+        (ec, byname, alternative_name, True) for ec, byname in entities
+    ]
+    return entities, parameter_values, entity_alternatives
+
+
+def _member_class_map(s):
+    """Map each relationship entity class to the element class of each of
+    its dimensions, for explicit member-entity emission."""
+    return {
+        "unit__node": ("unit", "node"),
+        "connection__node__node": ("connection", "node", "node"),
+        "group__reserve__upDown": ("reserve", "upDown", "group"),
+        "unit__reserve__upDown__node": ("unit", "reserve", "upDown", "node"),
+        "connection__reserve__upDown__node":
+            ("connection", "reserve", "upDown", "node"),
+    }
+
+
+def _member_entities(ec, byname, member_classes):
+    """Yield ``(element_class, (element,))`` for every member of a
+    relationship byname.  0-dim classes yield nothing extra (the entity
+    itself is already in the set)."""
+    dims = member_classes.get(ec)
+    if dims is None:
+        return
+    for elem_class, elem in zip(dims, byname):
+        yield (elem_class, (elem,))
+
+
+# ---------------------------------------------------------------------------
+# DataFrame -> Spine Map serialization
+# ---------------------------------------------------------------------------
+
+def df_to_spine_maps(df, spec, s, solve_name, *, par=None, alternative_name=None):
+    """Serialize one engine DataFrame into a list of
+    ``(entity_class, byname, value)`` triples per :data:`SPINEDB_OUTPUT_SPEC`.
+
+    The value is a (possibly nested) :class:`spinedb_api.parameter_value.Map`
+    with nesting ``[category ->] [solve ->] period [-> time] -> value`` and
+    any category dimension as the OUTERMOST key.
+    """
+    ec = spec["ec"]
+    has_time = spec["has_time"]
+
+    # Special period-less aggregated frames.
+    if spec.get("series_category"):
+        return _serialize_total_series(df, spec)
+
+    # Entity-in-index frames (capacity, indicator): the entity is an index
+    # level, columns are categories.
+    if spec.get("entity_index"):
+        return _serialize_entity_index(df, spec, s, solve_name)
+
+    df = _ensure_solve_level(df, s, has_time)
+
+    # Reduce the column MultiIndex / Index to a uniform tuple form and
+    # split into (entity-part, category-part).  Each yield is
+    # ``(byname, cat_key, series, row_ec)`` where ``row_ec`` overrides the
+    # spec entity class for that row (reserve-split routing) or is None.
+    rows = _iter_columns(df, spec, s)
+
+    out: list[tuple] = []
+    for byname, cat_key, series, row_ec in rows:
+        if byname is None:
+            continue
+        value = _series_to_map(series, has_time, cat_key,
+                               collapse_solve=spec.get("collapse_solve", False),
+                               solve_name=solve_name)
+        if value is None:
+            continue
+        out.append((row_ec or ec, byname, cat_key, value))
+
+    return _assemble_entity_values(out, spec)
+
+
+def _assemble_entity_values(rows, spec):
+    """Combine per-(entity, category) Maps into one value per entity.
+
+    When ``category == "header"`` the category dimension is the outermost
+    Map key; otherwise each entity has a single value column.
+    """
+    use_category = spec.get("category") == "header"
+    by_entity: dict[tuple, list[tuple]] = {}
+    order: list[tuple] = []
+    for row_ec, byname, cat_key, value in rows:
+        key = (row_ec, byname)
+        if key not in by_entity:
+            by_entity[key] = []
+            order.append(key)
+        by_entity[key].append((cat_key, value))
+
+    result: list[tuple] = []
+    for key in order:
+        ec, byname = key
+        items = by_entity[key]
+        if use_category:
+            keys, vals = [], []
+            for cat_key, value in items:
+                if value is None:
+                    continue
+                keys.append(_cat_key_str(cat_key))
+                vals.append(value)
+            if not keys:
+                continue
+            result.append((ec, byname, Map(keys, vals)))
+        else:
+            # No category nesting: a single value per entity.  If multiple
+            # source columns mapped to the same entity (e.g. output + input
+            # node frames merged), keep the first non-None.
+            value = next((v for _c, v in items if v is not None), None)
+            if value is None:
+                continue
+            result.append((ec, byname, value))
+    return result
+
+
+def _cat_key_str(cat_key):
+    """Render a category key (str or tuple) as a single Map index string."""
+    if cat_key is None:
+        return ""
+    if isinstance(cat_key, tuple):
+        return "__".join(str(x) for x in cat_key)
+    return str(cat_key)
+
+
+# ---------------------------------------------------------------------------
+# Column iteration / entity byname construction
+# ---------------------------------------------------------------------------
+
+def _iter_columns(df, spec, s):
+    """Yield ``(byname, category_key, series)`` for each data column.
+
+    ``byname`` is the entity byname tuple (schema dim order, ``updown``
+    normalized to ``upDown``).  ``category_key`` is the remaining column
+    levels (or None).  ``series`` is the index->value Series for that column.
+    """
+    entity_dims = spec["entity_dims"]
+    topology = spec.get("topology")
+    reserve_split = spec.get("reserve_split", False)
+    co2_type = spec.get("co2_type")
+    entity_filter = spec.get("entity_filter")
+
+    units = set(getattr(s, "process_unit", []))
+    connections = set(getattr(s, "process_connection", []))
+
+    # Fixed-entity (cost) frames: every column is a category.
+    if entity_dims == 0:
+        fixed = spec["fixed_entity"]
+        for col in df.columns:
+            yield fixed, col, df[col], None
+        return
+
+    triple_lookup = None
+    if topology == "connection_triple":
+        triple_lookup = _connection_triple_lookup(s)
+
+    for col in df.columns:
+        col_t = col if isinstance(col, tuple) else (col,)
+
+        if co2_type is not None:
+            # columns: (type, process, commodity, node)
+            ctype, process, commodity, node = col_t
+            if ctype != co2_type:
+                continue
+            yield (process,), (commodity, node), df[col], None
+            continue
+
+        if topology == "connection_triple":
+            conn = col_t[0]
+            triple = triple_lookup.get(conn)
+            if triple is None:
+                logger.debug("spinedb: no topology for connection '%s' — skipped",
+                             conn)
+                continue
+            yield triple, None, df[col], None
+            continue
+
+        if reserve_split:
+            # columns: (process, reserve, updown, node)
+            process, reserve, updown, node = col_t
+            byname = (process, reserve, _norm_updown(updown), node)
+            if process in units:
+                yield byname, None, df[col], "unit__reserve__upDown__node"
+                continue
+            if process in connections:
+                yield byname, None, df[col], "connection__reserve__upDown__node"
+                continue
+            logger.debug("spinedb: reserve process '%s' neither unit nor "
+                         "connection — skipped", process)
+            continue
+
+        if entity_filter == "unit" and col_t[0] not in units:
+            continue
+        if entity_filter == "connection" and col_t[0] not in connections:
+            continue
+
+        entity_part = col_t[:entity_dims]
+        cat_part = col_t[entity_dims:]
+        byname = tuple(_norm_updown(x) for x in entity_part)
+        cat = cat_part[0] if len(cat_part) == 1 else (cat_part or None)
+        if isinstance(cat, tuple) and not cat:
+            cat = None
+        yield byname, cat, df[col], None
+
+
+def _norm_updown(value):
+    """Normalize the ``updown`` label to schema's ``upDown`` spelling."""
+    if value == "updown":
+        return "upDown"
+    if value == "up":
+        return "up"
+    if value == "down":
+        return "down"
+    return value
+
+
+# ---------------------------------------------------------------------------
+# Series -> Map
+# ---------------------------------------------------------------------------
+
+def _series_to_map(series, has_time, cat_key, *, collapse_solve, solve_name):
+    """Convert a Series indexed by ``[solve,] period [, time]`` into a
+    nested Map ``[solve ->] period [-> time] -> value``.
+
+    ``collapse_solve`` aggregates the whole frame under a single
+    ``solve_name`` key (cost_discounted_solve — the engine frame lacks a
+    per-row solve axis).  Empty / all-NaN cells are dropped.
+    """
+    names = list(series.index.names)
+
+    if collapse_solve:
+        inner = _build_period_map(series, has_time, names)
+        if inner is None:
+            return None
+        return Map([str(solve_name)], [inner])
+
+    if "solve" in names:
+        solve_keys: list[str] = []
+        solve_vals: list = []
+        for solve, sub in series.groupby(level="solve", sort=False):
+            sub = sub.droplevel("solve")
+            inner = _build_period_map(sub, has_time,
+                                      [n for n in names if n != "solve"])
+            if inner is None:
+                continue
+            solve_keys.append(str(solve))
+            solve_vals.append(inner)
+        if not solve_keys:
+            return None
+        return Map(solve_keys, solve_vals)
+
+    # No solve level (could not be reconstructed) — wrap under solve_name.
+    inner = _build_period_map(series, has_time, names)
+    if inner is None:
+        return None
+    return Map([str(solve_name)], [inner])
+
+
+def _build_period_map(series, has_time, names):
+    """Build ``period -> [time ->] value`` from a Series whose index is
+    ``period [, time]`` (no solve level)."""
+    if has_time and "time" in names:
+        period_keys: list[str] = []
+        period_vals: list = []
+        for period, sub in series.groupby(level="period", sort=False):
+            sub = sub.droplevel("period") if sub.index.nlevels > 1 else sub
+            t_keys: list[str] = []
+            t_vals: list[float] = []
+            for time_idx, val in sub.items():
+                if _is_empty(val):
+                    continue
+                t_keys.append(str(time_idx))
+                t_vals.append(float(val))
+            if not t_keys:
+                continue
+            period_keys.append(str(period))
+            period_vals.append(Map(t_keys, t_vals))
+        if not period_keys:
+            return None
+        return Map(period_keys, period_vals)
+
+    # period -> value
+    p_keys: list[str] = []
+    p_vals: list[float] = []
+    if "period" in names and series.index.nlevels > 1:
+        series = series.groupby(level="period", sort=False).first()
+    for period_idx, val in series.items():
+        if _is_empty(val):
+            continue
+        p_keys.append(str(period_idx))
+        p_vals.append(float(val))
+    if not p_keys:
+        return None
+    return Map(p_keys, p_vals)
+
+
+def _is_empty(val) -> bool:
+    """True for NaN / None values that must not be emitted."""
+    if val is None:
+        return True
+    try:
+        return bool(math.isnan(val))
+    except (TypeError, ValueError):
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Solve reconstruction (mirrors the CSV branch, write_outputs.py:940-978)
+# ---------------------------------------------------------------------------
+
+def _ensure_solve_level(df, s, has_time):
+    """Add a ``solve`` index level to ``df`` if it lacks one, mirroring the
+    CSV branch logic.  Returns ``df`` unchanged when ``solve`` is already
+    present or no ``period`` level exists."""
+    names = list(df.index.names)
+    if "solve" in names or "period" not in names:
+        return df
+    df = df.copy()
+    if has_time and "time" in names:
+        spt = s.solve_period_time
+        if spt.droplevel("solve").duplicated().any():
+            spt = spt[~spt.droplevel("solve").duplicated(keep="last")]
+        pt_to_solve = dict(
+            zip(spt.droplevel("solve"), spt.get_level_values("solve")))
+        # Key off the named 'period'/'time' levels, not positional index
+        # slots — entity-first indexes (e.g. (unit, period, time)) otherwise
+        # read the wrong levels and miss every lookup.
+        period_level = df.index.get_level_values("period")
+        time_level = df.index.get_level_values("time")
+        solve_vals = [pt_to_solve.get((p, t), "")
+                      for p, t in zip(period_level, time_level)]
+        df.index = pd.MultiIndex.from_arrays(
+            [solve_vals] + [df.index.get_level_values(n) for n in df.index.names],
+            names=["solve"] + list(df.index.names),
+        )
+    else:
+        unique_sp = s.solve_period[
+            ~s.solve_period.droplevel("solve").duplicated(keep="last")]
+        period_to_solve = dict(zip(unique_sp.get_level_values("period"),
+                                   unique_sp.get_level_values("solve")))
+        if df.index.nlevels == 1:
+            solve_vals = df.index.map(lambda p: period_to_solve.get(p, ""))
+            df.index = pd.MultiIndex.from_arrays(
+                [solve_vals, df.index], names=["solve", df.index.name])
+        else:
+            period_level = df.index.get_level_values("period")
+            solve_vals = period_level.map(lambda p: period_to_solve.get(p, ""))
+            df.index = pd.MultiIndex.from_arrays(
+                [solve_vals] + [df.index.get_level_values(n)
+                                for n in df.index.names],
+                names=["solve"] + list(df.index.names),
+            )
+    return df
+
+
+# ---------------------------------------------------------------------------
+# Connection topology
+# ---------------------------------------------------------------------------
+
+def _connection_triple_lookup(s):
+    """Build ``connection -> (connection, node, node)`` from
+    ``s.process_source_sink`` filtered to connections.
+
+    The frames keyed by a bare connection name (``connection_dt_eee`` etc.)
+    need the (source, sink) nodes to form the ``connection__node__node``
+    byname.  The first matching ``(process, source, sink)`` row wins."""
+    lookup: dict[str, tuple] = {}
+    pss = getattr(s, "process_source_sink", None)
+    connections = set(getattr(s, "process_connection", []))
+    if pss is None:
+        return lookup
+    for process, source, sink in pss:
+        if process not in connections:
+            continue
+        if process not in lookup:
+            lookup[process] = (process, source, sink)
+    return lookup
+
+
+# ---------------------------------------------------------------------------
+# Cost helpers
+# ---------------------------------------------------------------------------
+
+def _serialize_total_series(series, spec):
+    """Serialize ``costs_discounted_p_`` (a per-category Series, no period
+    axis) into one ``Map(category -> value)`` for entity ``("model",)``."""
+    if isinstance(series, pd.DataFrame):
+        # to_frame() of a Series yields a 1-column frame; squeeze it back.
+        if series.shape[1] == 1:
+            series = series.iloc[:, 0]
+        else:
+            return []
+    keys, vals = [], []
+    for cat, val in series.items():
+        if _is_empty(val):
+            continue
+        keys.append(_cat_key_str(cat))
+        vals.append(float(val))
+    if not keys:
+        return []
+    return [(spec["ec"], spec["fixed_entity"], Map(keys, vals))]
+
+
+def _serialize_entity_index(df, spec, s, solve_name):
+    """Serialize an entity-in-index frame (capacity / indicator): index is
+    ``(entity[, period[, time]])`` and columns are categories.
+
+    Emits ``(ec, (entity,), Map(category -> [solve ->] period [-> time]))``
+    per entity, dropping all-empty cells / categories."""
+    ec = spec["ec"]
+    has_time = spec["has_time"]
+    entity_level = spec["entity_index"]
+    if entity_level not in (df.index.names or []):
+        logger.debug("spinedb: entity level '%s' not in index of '%s' — skipped",
+                     entity_level, spec["param"])
+        return []
+
+    result: list[tuple] = []
+    for entity, sub in df.groupby(level=entity_level, sort=False):
+        sub = sub.droplevel(entity_level)
+        sub = _ensure_solve_level(sub, s, has_time)
+        cat_keys: list[str] = []
+        cat_vals: list = []
+        for col in sub.columns:
+            value = _series_to_map(sub[col], has_time, None,
+                                   collapse_solve=False, solve_name=solve_name)
+            if value is None:
+                continue
+            cat_keys.append(_cat_key_str(col))
+            cat_vals.append(value)
+        if not cat_keys:
+            continue
+        result.append((ec, (entity,), Map(cat_keys, cat_vals)))
+    return result
+
+
+def _discount_factor_map(par, attr, s, solve_name):
+    """Build a ``Map(solve -> period -> value)`` from a per-period Series on
+    ``par`` (the inflation factors).  Returns None when unavailable/empty."""
+    series = getattr(par, attr, None)
+    if series is None:
+        return None
+    if isinstance(series, pd.DataFrame):
+        if series.shape[1] != 1:
+            return None
+        series = series.iloc[:, 0]
+    if not isinstance(series, pd.Series) or series.empty:
+        return None
+    # Period -> solve reconstruction, then nest solve -> period -> value.
+    period_to_solve = None
+    sp = getattr(s, "solve_period", None)
+    if sp is not None:
+        unique_sp = sp[~sp.droplevel("solve").duplicated(keep="last")]
+        period_to_solve = dict(zip(unique_sp.get_level_values("period"),
+                                   unique_sp.get_level_values("solve")))
+    by_solve: dict[str, list] = {}
+    order: list[str] = []
+    for period, val in series.items():
+        if _is_empty(val):
+            continue
+        solve = (period_to_solve.get(period) if period_to_solve else None) \
+            or solve_name
+        solve = str(solve)
+        if solve not in by_solve:
+            by_solve[solve] = ([], [])
+            order.append(solve)
+        by_solve[solve][0].append(str(period))
+        by_solve[solve][1].append(float(val))
+    if not order:
+        return None
+    solve_keys, solve_vals = [], []
+    for solve in order:
+        pk, pv = by_solve[solve]
+        solve_keys.append(solve)
+        solve_vals.append(Map(pk, pv))
+    return Map(solve_keys, solve_vals)
+
+
+# ---------------------------------------------------------------------------
+# Alternative purge
+# ---------------------------------------------------------------------------
+
+def _purge_alternative(db_url, alternative_name):
+    """Delete existing ``parameter_value`` items in ``alternative_name`` so a
+    re-run replaces rather than duplicates.  Entities are shared across
+    alternatives and are not purged."""
+    with DatabaseMapping(db_url) as db:
+        items = db.get_parameter_value_items(alternative_name=alternative_name)
+        if not items:
+            return
+        for item in items:
+            db.remove_item("parameter_value", item["id"])
+        db.commit_session(f"Purge results alternative: {alternative_name}")