Phase 0 notes ============= 2026-10-02 -- versioned environments in seamm-manager ----------------------------------------------------- Done on ``seamm_manager`` ``dev`` (uncommitted to main, unreleased): the rule "never update a venv in place while jobs run". - ``/venv`` becomes a symlink to ``/venvs/``. An update builds the new version from ``uv pip freeze`` of the current one (4 s with uv's cache, 1.3 GB; editable and local installs survive), applies the change there, and switches the link. - CPython does not resolve the link when it locates a venv, so every launcher (launchd plist, systemd unit, service bundle, desktop apps, the migrated scripts' shebangs) is rewritten to the real path. A switch is refused while a process started through the link exists; ``--force`` overrides. - New: ``environment versions | migrate | switch | rollback | prune``; ``recreate`` builds beside instead of deleting. - Validated on ``~/SEAMM_DEV``: migration under a running JobServer; a real update of ``seamm`` 2026.10.2 to 2026.10.2.2 whose switch was refused by a link-started process and completed later with ``environment switch``; rollback and back; prune keeps in-use and young versions; job 4002 reported ``sys.prefix`` under ``venvs/``. Found on the way ~~~~~~~~~~~~~~~~ - ``Uv.install(..., upgrade=True)`` without a lock passes every installed package's requirements as ``-r`` context; with ``--upgrade`` uv treats those as requests and upgrades them too (the old environment's ``seamm`` and ``seamm-manager`` moved during the development-packages step). The development packages now ride along in the new build, which closes the leak for updates, but the ``-r`` semantics deserve a look. - ``venv-webui`` is still updated in place (no jobs run from it; a restart is a brief outage). Same treatment later if wanted. - The plug-in installers update the codes' conda environments in place; the Python-based engines (xnn, the MOPAC MDI engine) import lazily too. The comparison harness (same day) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``seamm-manager compare -a -b [--work DIR] [-- args]`` runs the flowchart with each side's ``run_flowchart`` (``--root`` set to the side's installation) in ``a/`` and ``b/`` and compares the trees: JSON, CSV and structure files with a numeric tolerance (``--rtol``, ``--atol``), text files after dropping lines with timestamps, durations, versions and hosts and replacing the working directories. Sides: ``current``, ``newest``, ``previous``, a version name, an environment directory, an installation root. So the check before a switch is ``compare x.flow -a current -b newest``. Validated with ``Testing/harness_water.flow`` (FromSMILES + MOPAC energy) between the two SEAMM_DEV versions and between ~/SEAMM and SEAMM_DEV: every file identical or within tolerance once MOPAC's timing lines and the job uuid were treated as volatile. Found: ``seamm_util.root.installation_root`` keyed on a directory named ``venv``, so anything run by hand from a versioned environment defaulted to ``~/SEAMM`` (jobs were fine: the JobServer passes ``--root``). Fixed on ``seamm_util`` ``dev``; **seamm_util must be released before seamm-manager's migration reaches a production installation.** Released and rolled out (2026-10-02, afternoon) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - seamm_util 2026.10.2 (root fix; CI on uv) and seamm-manager 2026.10.2.1 are on PyPI. ``~/SEAMM`` is migrated (``venvs/2026-10-02T15-02-40``, JobServer and apps relinked); ``update --latest seamm-util`` built ``venvs/2026-10-02T15-03-12`` with seamm_util 2026.10.2 but the switch was refused: five ``seamm-flowchart`` MCP servers of Claude sessions were started through the link before the migration. They are the only link-started processes; once restarted, every later production switch is unguarded. - Found: ``sync_manager()`` ran after the build against the *current* environment when the switch was refused -- an in-place change. Fixed on seamm_manager dev (unreleased): the manager's release is installed into the new environment during the build. - Found: ``uv tool install --force --refresh seamm-manager`` without a version or ``--python`` resolved 2026.9.26.1, not the newest; with ``--python 3.12`` and the version it is fine. The manager's own self-upgrade passes ``--python``, so ``update --all`` is unaffected; by hand, pin both. Still to do in phase 0 ~~~~~~~~~~~~~~~~~~~~~~ - Switch ~/SEAMM to the new version once the link-started MCP servers are restarted; release the sync_manager fix; migrate paul.local, then ChemAI (on an explicit ask) and ARC. - Broaden the harness's corpus: a loop with a table, an ORCA step, a Write Structure step, so phase 4 (tables in the database) has its gate.