processforge 0.3.23__tar.gz → 0.3.26__tar.gz

{processforge-0.3.23/src/processforge.egg-info → processforge-0.3.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: processforge
-Version: 0.3.23
+Version: 0.3.26
 Summary: A Python-based process simulation framework for chemical engineering applications.
 Author-email: Processforge Team <team@processforge.dev>
 License-Expression: BSD-3-Clause

{processforge-0.3.23 → processforge-0.3.26}/flowsheets/hydraulic-chain.json

@@ -105,7 +105,7 @@
   "simulation": {
     "mode": "steady",
     "t0": 0.0,
-    "tf": 25.0,
+    "tf": 15.0,
     "dt": 1.0
   }
 }

{processforge-0.3.23 → processforge-0.3.26}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "processforge"
-version = "0.3.23"
+version = "0.3.26"
 description = "A Python-based process simulation framework for chemical engineering applications."
 readme = "README.md"
 license = "BSD-3-Clause"

{processforge-0.3.23 → processforge-0.3.26}/src/processforge/__init__.py

@@ -30,7 +30,7 @@ from .units.flash import Flash
 from .units.heater import Heater
 from .eo import EOFlowsheet, EOSolver
 
-__version__ = "0.3.23"
+__version__ = "0.3.26"
 
 __all__ = [
     "Flowsheet",

{processforge-0.3.23 → processforge-0.3.26}/src/processforge/cli/apply.py

@@ -6,46 +6,10 @@ import os
 import time
 from typing import Literal
 
-import hashlib
-import json
-import os
 import typer
-from datetime import datetime, timezone
 from loguru import logger
 
-
-def _persist_run(archive, fs, results, run_info, config, base_name, snapshot_id):
-    """Build a standardized RunManifest and persist it to the archive."""
-    run_id = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ") + "_" + os.urandom(3).hex()
-    flowsheet_hash = hashlib.sha256(
-        json.dumps(config, sort_keys=True, default=str).encode("utf-8")
-    ).hexdigest()[:16]
-    manifest = fs.collect_outputs(
-        run_id, config.get("simulation", {}).get("mode", "steady"),
-        base_name, provenance=run_info.model_dump(),
-    )
-    manifest.snapshot_id = snapshot_id
-    stream_results = {k: v for k, v in results.items() if not hasattr(v, "fields")}
-    archive.save_run(manifest, stream_results=stream_results)
-
-    # Always persist a Zarr copy of the standardized outputs (fields + artifacts)
-    # inside the archive, mirroring `pf run`.
-    try:
-        from ..result import relink_latest_results, save_results_zarr
-
-        run_results_dir = os.path.join(archive.path, "results", run_id)
-        save_results_zarr(
-            results,
-            os.path.join(run_results_dir, "results.zarr"),
-            run_info,
-        )
-        relink_latest_results(archive.path, run_id)
-    except Exception as e:
-        logger.warning(f"Failed to write results.zarr: {type(e).__name__}: {e}")
-
-    logger.info(f"Run saved    : {run_id}")
-    return run_id
-
+from .persist import make_run_id, persist_run
 from ..eo import EOFlowsheet
 from ..provenance import build_run_info
 from .common import (
@@ -63,7 +27,7 @@ from .common import (
     write_divergence_report,
 )
 
-from .display import print_structural_diff
+from .display import print_param_drift, print_structural_diff
 
 
 def apply(
@@ -131,16 +95,9 @@ def apply(
         if not drifted:
             logger.info("No drift detected. System is already at the desired state.")
             return
-        stream_drifts = [d for d in drifted if d.startswith("streams.")]
-        unit_drifts = [d for d in drifted if d.startswith("units.")]
-        other_drifts = [d for d in drifted if not d.startswith(("streams.", "units."))]
         logger.warning("Drift detected:")
-        if stream_drifts:
-            logger.warning(f"  Stream drift : {stream_drifts}")
-        if unit_drifts:
-            logger.warning(f"  Unit drift   : {unit_drifts}")
-        if other_drifts:
-            logger.warning(f"  Config drift : {other_drifts}")
+        old_config = state.config if hasattr(state, "config") else state.get("config", {})
+        print_param_drift(drifted, old_config, config)
 
     # Build flowsheet; attach saved state for warm-start unless topology changed
     fs = EOFlowsheet(config, backend=backend)
@@ -165,14 +122,15 @@ def apply(
             label="converged state",
         )
         run_info = build_run_info(config, x0=fs.x0, var_names=fs.var_names)
-        saved_run_id = _persist_run(sm, fs, results, run_info, config, base_name, snapshot_id)
+        run_id = make_run_id()
+        persist_run(sm, fs, run_id, results, run_info, config, base_name, snapshot_id)
         logger.info("=== Apply Summary ===")
         logger.info("  Status       : CONVERGED")
         logger.info(f"  Final ||F||  : {fs.solver_stats.get('final_norm', '?'):.3e}")
         logger.info(f"  Iterations   : {fs.solver_stats.get('iterations', '?')}")
         logger.info(f"  Backend      : {display_backend(config, fs.backend)}")
         logger.info(f"  Snapshot ID  : {snapshot_id}")
-        logger.info(f"  Run ID       : {saved_run_id}")
+        logger.info(f"  Run ID       : {run_id}")
         logger.info(f"  Elapsed (s)  : {elapsed:.2f}")
         return
 
@@ -187,25 +145,31 @@ def apply(
         tmp_fs = _EO(config, backend=backend)
         manager = tmp_fs._build()
         try:
-            x_hom, hom_converged, hom_stats = solve_with_homotopy(
-                tmp_fs, manager, solver, state, drifted
-            )
+            homotopy_result = solve_with_homotopy(tmp_fs, manager, solver, state, drifted)
+            if homotopy_result.converged:
+                # Assemble the real (converged) outputs from the homotopy
+                # solution while the providers are still alive. The `results`
+                # from the earlier failed direct solve must NOT be persisted.
+                tmp_fs.assemble_from_solution(
+                    manager, homotopy_result.x_solution, True, homotopy_result.stats
+                )
         finally:
             teardown_providers(tmp_fs._provider_map)
 
-        if hom_converged:
+        if homotopy_result.converged:
             logger.info(
-                f"Homotopy converged: ||F||={hom_stats.get('final_norm', '?'):.3e}, "
-                f"iterations={hom_stats.get('iterations', '?')}"
+                f"Homotopy converged: ||F||={homotopy_result.stats.get('final_norm', '?'):.3e}, "
+                f"iterations={homotopy_result.stats.get('iterations', '?')}"
             )
-            save_snapshot(
-                sm, config, x_hom, fs.var_names,
+            snapshot_id = save_snapshot(
+                sm, config, homotopy_result.x_solution, fs.var_names,
                 metadata=current_metadata,
                 parent_snapshot_id=state.snapshot_id if state is not None and not topology_changed else None,
                 label="homotopy solution",
             )
             run_info = build_run_info(config, x0=fs.x0, var_names=fs.var_names)
-            _persist_run(sm, fs, results, run_info, config, base_name, snapshot_id)
+            run_id = make_run_id()
+            persist_run(sm, tmp_fs, run_id, tmp_fs.results, run_info, config, base_name, snapshot_id)
             logger.info("Homotopy apply succeeded. New snapshot saved.")
             return
 
@@ -217,8 +181,8 @@ def apply(
         breakdown = log_residual_breakdown(fs)
         divergence = build_divergence_report(
             drifted_params=drifted,
-            solver_stats=hom_stats,
-            x_last=x_hom,
+            solver_stats=homotopy_result.stats,
+            x_last=homotopy_result.x_solution,
             var_names=fs.var_names,
             breakdown=breakdown,
         )

{processforge-0.3.23 → processforge-0.3.26}/src/processforge/cli/common.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import datetime
 import hashlib
-import importlib
+import importlib.util
 import json
 import os
 import urllib.error

{processforge-0.3.23 → processforge-0.3.26}/src/processforge/cli/display.py

@@ -4,6 +4,8 @@ from __future__ import annotations
 
 from typing import Any
 
+import importlib.util
+
 from loguru import logger
 
 
@@ -53,7 +55,7 @@ def print_unit_mismatches(mismatches: list[Any]) -> None:
             logger.warning(f"Unit annotation — stream '{m.stream_name}'.{m.property_name}: {m.message}")
 
 
-def print_provider_health(config: dict) -> list[str]:
+def print_provider_health(config: dict, strict: bool = False) -> list[str]:
     """Log per-provider reachability for flowsheets using Docker containers.
 
     For each provider declared in *config*:
@@ -63,10 +65,9 @@ def print_provider_health(config: dict) -> list[str]:
     * pip-installable providers are reported as importable or not.
 
     Returns a list of failure messages — one per unreachable containerized
-    provider (empty means every provider is healthy/available).
+    provider (empty means every provider is healthy/available). When *strict*
+    is True, a missing pip-installable provider is also appended to failures.
     """
-    import importlib
-
     from ..providers.registry import is_containerized, _PROVIDER_CATALOG
 
     providers = config.get("providers", {})
@@ -104,6 +105,10 @@ def print_provider_health(config: dict) -> list[str]:
                 dep = catalog.get("optional_dep")
                 hint = f"pip install 'processforge[{dep}]'" if dep else "built-in"
                 logger.warning(f"  [WARN] {name} [{ptype}] — not installed ({hint})")
+                if strict:
+                    failures.append(
+                        f"Provider '{name}' not installed ({hint})"
+                    )
 
     return failures
 
@@ -122,3 +127,26 @@ def print_structural_diff(diff: dict) -> None:
         logger.info(f"  - {name:<20} [{unit_type}]  (removed)")
     if not any(diff.get(k) for k in ("added", "modified", "removed")):
         logger.info("  (no structural changes)")
+
+
+def _resolve_path(cfg: dict, path: str) -> object:
+    """Resolve a dotted config path (e.g. ``simulation.tf``) to its value."""
+    cur: object = cfg
+    for part in path.split("."):
+        if isinstance(cur, dict) and part in cur:
+            cur = cur[part]
+        else:
+            return "<missing>"
+    return cur
+
+
+def print_param_drift(drifted: list[str], old_config: dict, new_config: dict) -> None:
+    """Log parameter drift paths with their old → new values."""
+    logger.info("=== Parameter Drift vs. Saved State ===")
+    if not drifted:
+        logger.info("  (no parameter changes)")
+        return
+    for path in drifted:
+        old_val = _resolve_path(old_config, path)
+        new_val = _resolve_path(new_config, path)
+        logger.info(f"  ~ {path}: {old_val!r} → {new_val!r}")

{processforge-0.3.23 → processforge-0.3.26}/src/processforge/cli/init.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-import importlib
+import importlib.util
 import json
 import os
 import shutil
@@ -11,8 +11,18 @@ import subprocess
 import typer
 from loguru import logger
 
-from .common import extract_providers, is_local_provider_url
-from ..lock import flowsheet_env_dir, read_lock
+from .common import (
+    extract_providers,
+    is_local_provider_url,
+)
+from ..lock import flowsheet_env_dir, read_lock, write_lock
+from ..providers.registry import (
+    get_provider_docker_image,
+    get_provider_default_port,
+    is_containerized,
+    _PROVIDER_CATALOG,
+)
+from ..utils.validate_flowsheet import validate_flowsheet
 
 
 def _migrate_legacy_env(pf_dir: str) -> None:
@@ -21,7 +31,9 @@ def _migrate_legacy_env(pf_dir: str) -> None:
     Older processforge stored a single environment at ``.processforge/lock.json``
     and ``.processforge/docker-compose.yml``. This relocates those into the hashed
     env dir derived from the flowsheet recorded in the legacy lock, so an existing
-    repo keeps its provider environment after upgrading.
+    repo keeps its provider environment after upgrading. The target always uses the
+    same hashed env dir that ``pf init``/``read_lock`` locate, so the migrated env
+    is never orphaned.
     """
     legacy_lock = os.path.join(pf_dir, "lock.json")
     legacy_compose = os.path.join(pf_dir, "docker-compose.yml")
@@ -35,15 +47,19 @@ def _migrate_legacy_env(pf_dir: str) -> None:
         except Exception:
             recorded = None
 
-    if recorded and os.path.exists(recorded):
-        env_dir = flowsheet_env_dir(pf_dir, recorded)
+    # Always target the hashed env dir keyed by the recorded flowsheet path so it
+    # matches what `pf init <flowsheet>` / `read_lock` expect on subsequent runs.
+    env_dir = flowsheet_env_dir(pf_dir, recorded or "legacy")
+    if recorded:
+        logger.info(
+            f"Migrating legacy .processforge/lock.json + docker-compose.yml into "
+            f"'{os.path.relpath(env_dir, pf_dir)}/'."
+        )
     else:
-        base = os.path.splitext(os.path.basename(recorded or "legacy"))[0] or "legacy"
-        env_dir = os.path.join(pf_dir, base)
         logger.warning(
             "Migrating legacy .processforge/lock.json + docker-compose.yml into "
-            f"'{os.path.relpath(env_dir, pf_dir)}/' (recorded flowsheet not found on "
-            "disk — re-run `pf init <flowsheet.json>` to restore the correct env dir)."
+            f"'{os.path.relpath(env_dir, pf_dir)}/' (no recorded flowsheet found — "
+            "re-run `pf init <flowsheet.json>` to restore the correct env dir)."
         )
 
     if os.path.exists(env_dir):
@@ -73,15 +89,19 @@ def init(
         "--path",
         help="Root directory to initialise in (default: current directory)",
     ),
+    no_pull: bool = typer.Option(
+        False,
+        "--no-pull",
+        help="Generate docker-compose.yml but skip pulling provider images",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="Re-initialise even if the environment already exists",
+    ),
 ) -> None:
     """Initialise the .processforge/ project directory."""
-    from ..providers.registry import (
-        is_containerized,
-        get_provider_docker_image,
-        get_provider_default_port,
-        _PROVIDER_CATALOG,
-    )
-    from ..lock import write_lock
     from ..compose import generate_compose
 
     root = path or "."
@@ -96,17 +116,6 @@ def init(
     # dir so existing repos aren't silently broken by the new structure.
     _migrate_legacy_env(pf_dir)
 
-    # Remove stale .pfstate snapshot directories from outputs/
-    stale_count = 0
-    for entry in os.listdir(outputs_dir):
-        if entry.endswith(".pfstate"):
-            stale = os.path.join(outputs_dir, entry)
-            if os.path.isdir(stale):
-                shutil.rmtree(stale)
-                stale_count += 1
-    if stale_count:
-        logger.info(f"Removed {stale_count} stale snapshot(s) from {outputs_dir}/.")
-
     # Write config.json (always)
     config_path = os.path.join(pf_dir, "config.json")
     if not os.path.exists(config_path):
@@ -121,6 +130,26 @@ def init(
     else:
         logger.info(f"{config_path} already exists — skipped.")
 
+    # Honour a configured outputs_dir for the rest of init.
+    outputs_dir_name = "outputs"
+    try:
+        with open(config_path, encoding="utf-8") as f:
+            outputs_dir_name = json.load(f).get("outputs_dir", "outputs")
+    except Exception:
+        pass
+    outputs_dir = os.path.join(root, outputs_dir_name)
+
+    # Remove stale .pfstate snapshot directories from outputs/
+    stale_count = 0
+    for entry in os.listdir(outputs_dir):
+        if entry.endswith(".pfstate"):
+            stale = os.path.join(outputs_dir, entry)
+            if os.path.isdir(stale):
+                shutil.rmtree(stale)
+                stale_count += 1
+    if stale_count:
+        logger.info(f"Removed {stale_count} stale snapshot(s) from {outputs_dir}/.")
+
     # No flowsheet → scaffold only
     if not flowsheet:
         logger.info(".processforge/ initialised successfully.")
@@ -131,15 +160,21 @@ def init(
     flowsheet_path = flowsheet
     if not os.path.exists(flowsheet_path):
         logger.error(f"Flowsheet '{flowsheet_path}' not found.")
-        raise SystemExit(1)
+        raise typer.Exit(code=1)
+
+    try:
+        validate_flowsheet(flowsheet_path)
+    except Exception as e:
+        logger.error(f"Failed to validate flowsheet '{flowsheet_path}': {e}")
+        raise typer.Exit(code=1)
 
     providers = extract_providers(flowsheet_path)
     logger.info(f"Reading providers from {flowsheet_path}...")
 
-    # Categorize providers
-    pip_providers: dict[str, dict] = {}
+    # Categorize providers, reusing the shared local/remote/pip classification.
     local_docker_providers: dict[str, dict] = {}
     remote_docker_providers: dict[str, dict] = {}
+    pip_providers: dict[str, dict] = {}
     for name, cfg in providers.items():
         ptype = cfg.get("type", "")
         if is_containerized(ptype):
@@ -151,7 +186,8 @@ def init(
                 local_docker_providers[name] = {
                     "type": ptype,
                     "url": url,
-                    "docker_image": cfg.get("docker_image") or get_provider_docker_image(ptype),
+                    "docker_image": cfg.get("docker_image")
+                    or get_provider_docker_image(ptype),
                     "port": port,
                 }
                 logger.info(f"  {name}: type={ptype}, url={url} (Docker, local)")
@@ -159,7 +195,8 @@ def init(
                 remote_docker_providers[name] = {
                     "type": ptype,
                     "url": url,
-                    "docker_image": cfg.get("docker_image") or get_provider_docker_image(ptype),
+                    "docker_image": cfg.get("docker_image")
+                    or get_provider_docker_image(ptype),
                 }
                 logger.info(
                     f"  {name}: type={ptype}, url={url} (Docker, remote — skipping compose)"
@@ -185,45 +222,48 @@ def init(
     # Providers with an explicit remote URL are assumed to be running elsewhere
     # (e.g. a cloud deployment of the ghcr.io image) and are not touched here.
     if local_docker_providers:
-        compose_path = os.path.join(
-            flowsheet_env_dir(pf_dir, flowsheet_path), "docker-compose.yml"
-        )
-        if os.path.exists(compose_path):
+        env_dir = flowsheet_env_dir(pf_dir, flowsheet_path)
+        compose_path = os.path.join(env_dir, "docker-compose.yml")
+        if os.path.exists(compose_path) and not force:
             logger.warning(
                 f"Environment already initialized — reinitializing from {flowsheet_path}"
             )
 
-        generate_compose(pf_dir, local_docker_providers, outputs_dir, flowsheet=flowsheet_path)
+        generate_compose(
+            pf_dir, local_docker_providers, outputs_dir, flowsheet=flowsheet_path
+        )
         logger.info(f"Generated {compose_path}")
 
-        # Attempt docker compose pull — stream progress live
-        try:
-            logger.info("Pulling Docker images (this may take a while)...")
-            process = subprocess.Popen(
-                ["docker", "compose", "-f", compose_path, "pull"],
-                stdout=subprocess.PIPE,
-                stderr=subprocess.STDOUT,
-                text=True,
-                bufsize=1,
-            )
-            assert process.stdout is not None
-            for line in process.stdout:
-                line = line.rstrip()
-                if line:
-                    logger.info(line)
-            returncode = process.wait(timeout=600)
-            if returncode == 0:
-                logger.info("Pulled Docker images.")
-            else:
+        if no_pull:
+            logger.info("Skipping Docker image pull (--no-pull).")
+        else:
+            # Attempt docker compose pull. Capture output and stream it via the
+            # logger; on timeout the child is reaped (subprocess.run kills it)
+            # so no orphaned/blocked process is left behind.
+            try:
+                logger.info("Pulling Docker images (this may take a while)...")
+                result = subprocess.run(
+                    ["docker", "compose", "-f", compose_path, "pull"],
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.STDOUT,
+                    text=True,
+                    timeout=600,
+                )
+                for line in result.stdout.splitlines():
+                    if line.strip():
+                        logger.info(line)
+                if result.returncode == 0:
+                    logger.info("Pulled Docker images.")
+                else:
+                    logger.warning(
+                        f"docker compose pull failed with exit code {result.returncode}."
+                    )
+            except FileNotFoundError:
                 logger.warning(
-                    f"docker compose pull failed with exit code {returncode}."
+                    "Docker not found. Install Docker to use containerized providers."
                 )
-        except FileNotFoundError:
-            logger.warning(
-                "Docker not found. Install Docker to use containerized providers."
-            )
-        except subprocess.TimeoutExpired:
-            logger.warning("docker compose pull timed out after 600s.")
+            except subprocess.TimeoutExpired:
+                logger.warning("docker compose pull timed out after 600s.")
 
         logger.info(
             "To start the containerized provider(s), run:\n"
@@ -242,15 +282,19 @@ def init(
     else:
         logger.info("No containerized providers — skipping Docker setup.")
 
-    # Write lock file
+    # Write lock file, reusing the shared URL resolution for the recorded url.
     lock_providers: dict[str, dict] = {}
     for name, cfg in providers.items():
         ptype = cfg.get("type", "")
         if is_containerized(ptype):
+            url = cfg.get("url")
+            if not url:
+                port = get_provider_default_port(ptype) or 9000
+                url = f"http://localhost:{port}"
             lock_providers[name] = {
-                "docker_image": cfg.get("docker_image") or get_provider_docker_image(ptype),
-                "url": cfg.get("url")
-                or f"http://localhost:{get_provider_default_port(ptype) or 9000}",
+                "docker_image": cfg.get("docker_image")
+                or get_provider_docker_image(ptype),
+                "url": url,
             }
         else:
             lock_providers[name] = {
@@ -261,5 +305,7 @@ def init(
     from .. import __version__ as pf_version
 
     write_lock(pf_dir, flowsheet_path, lock_providers, pf_version)
-    logger.info(f"Wrote {os.path.join(flowsheet_env_dir(pf_dir, flowsheet_path), 'lock.json')}")
+    logger.info(
+        f"Wrote {os.path.join(flowsheet_env_dir(pf_dir, flowsheet_path), 'lock.json')}"
+    )
     logger.info(".processforge/ initialised successfully.")

processforge-0.3.26/src/processforge/cli/persist.py

@@ -0,0 +1,99 @@
+"""Shared run-persistence helpers for the ``pf run`` / ``pf apply`` CLIs.
+
+Both commands build a :class:`~processforge.types.RunManifest`, save it to the
+:class:`~processforge.persistence.archive.ProcessStateArchive`, and write a Zarr
+copy of the standardized outputs. That logic was previously duplicated (with
+slightly different bugs in each copy); it now lives here in one place.
+"""
+
+from __future__ import annotations
+
+import datetime
+import hashlib
+import json
+import os
+from typing import TYPE_CHECKING, Any
+
+from loguru import logger
+
+if TYPE_CHECKING:
+    from ..persistence.archive import ProcessStateArchive
+    from ..types import RunInfo
+
+_RUN_ID_TS_FMT = "%Y%m%dT%H%M%SZ"
+
+
+def make_run_id() -> str:
+    """Build a unique, sortable run id: ``<UTC timestamp>_<6 hex bytes>``."""
+    return (
+        datetime.datetime.now(datetime.timezone.utc).strftime(_RUN_ID_TS_FMT)
+        + "_"
+        + os.urandom(3).hex()
+    )
+
+
+def flowsheet_hash(config: dict) -> str:
+    """Short (16-hex) sha256 of a flowsheet config for run/index correlation."""
+    return hashlib.sha256(
+        json.dumps(config, sort_keys=True, default=str).encode("utf-8")
+    ).hexdigest()[:16]
+
+
+def persist_run(
+    archive: "ProcessStateArchive",
+    fs: Any,
+    run_id: str,
+    results: dict,
+    run_info: "RunInfo | dict",
+    config: dict,
+    base_name: str,
+    snapshot_id: str | None = None,
+) -> str:
+    """Persist a run's manifest + Zarr outputs into *archive*.
+
+    Args:
+        archive: The :class:`ProcessStateArchive` for this flowsheet.
+        fs: The flowsheet object that produced *results* (must expose
+            ``collect_outputs``). Either ``EOFlowsheet`` or ``Flowsheet``.
+        run_id: Unique run id (use :func:`make_run_id`).
+        results: The solve's stream/unit result dict (the *converged* one).
+        run_info: Provenance from
+            :func:`processforge.provenance.build_run_info`.
+        config: Validated flowsheet config (for the simulation mode).
+        base_name: Flowsheet basename used for archive paths.
+        snapshot_id: Optional snapshot id to stamp on the manifest (so a run
+            can be linked back to the state it was derived from).
+
+    Returns:
+        The run id that was persisted.
+    """
+    mode = config.get("simulation", {}).get("mode", "steady")
+    run_info_dump = (
+        run_info.model_dump() if hasattr(run_info, "model_dump") else run_info
+    )
+    manifest = fs.collect_outputs(
+        run_id, mode, base_name, provenance=run_info_dump
+    )
+    if snapshot_id is not None:
+        manifest.snapshot_id = snapshot_id
+
+    stream_results = {k: v for k, v in results.items() if not hasattr(v, "fields")}
+    archive.save_run(manifest, stream_results=stream_results)
+
+    # Always persist a Zarr copy of the standardized outputs (fields + artifacts)
+    # inside the archive, mirroring `pf run`.
+    try:
+        from ..result import relink_latest_results, save_results_zarr
+
+        run_results_dir = os.path.join(archive.path, "results", run_id)
+        save_results_zarr(
+            results,
+            os.path.join(run_results_dir, "results.zarr"),
+            run_info,
+        )
+        relink_latest_results(archive.path, run_id)
+    except Exception as e:
+        logger.warning(f"Failed to write results.zarr: {type(e).__name__}: {e}")
+
+    logger.info(f"Run saved    : {run_id}")
+    return run_id