Add merge_networks (closes #221)

[dotsdl]

Summary

Revives the work originally proposed in #433 (now unreachable since the contributing fork was deleted) and finishes it.

• Adds Neo4jStore.merge_networks for combining multiple existing AlchemicalNetwork\s into a new AlchemicalNetwork in a target Scope, with completed and errored Task\s (and their ProtocolDAGResultRef\s) cloned into the new scope so previously-computed results do not need to be re-run. (Originally authored by @ianmkenney; preserved here as-is, then refactored — see commits.)
• Adds the user-facing surface:
  • POST /networks/merge on AlchemiscaleAPI, which validates the destination Scope and each source network's Scope against the caller's token before delegating to the store.
  • AlchemiscaleClient.merge_networks(networks, name, scope), with client-side guards for wildcard scopes, empty input, and non-AlchemicalNetwork ScopedKey\s.
• Refactors the database-layer implementation to use KeyedChain.decode_subchains (gufe ≥1.8.0), which replaces a hand-rolled kc_to_gufe helper plus manual chain-slicing loop, and lifts the inline TransformationData dataclass to a private module-level _TransformationData for readability.
• Bumps the gufe pin to >=1.8.0 in devtools/conda-envs/test.yml and devtools/conda-envs/alchemiscale-server.yml (the only env files that actually exercise this code path).
• Adds integration tests at both the API and client layers covering: happy-path edge union, scope-based authorization (bad destination and bad source), and full preservation of complete/error Task\s with their ProtocolDAGResultRef\s — including a reachability check via get_network_tasks(merged_sk).

Closes #221.

Notes for reviewers

• The store-level merge_networks body is unchanged in behavior from the original PR; the diff against Allow server-side copying and merging of AlchemicalNetworks #433's last revision is the decode_subchains refactor plus the lift of TransformationData.
• The get_network_tasks assertion in test_merge_networks_preserves_tasks_and_results exercises the standard (:AlchemicalNetwork)-[:DEPENDS_ON]->(:Transformation)<-[:PERFORMS]-(:Task) traversal on the merged network. If it fails, that indicates a missing PERFORMS edge in _TransformationData.to_subgraph — flagged here for follow-up rather than fixed in this PR, since the original implementation has the same behavior.
• subchain_cache is preserved with cleaner contents (KeyedChain.from_gufe(transformation)) but its necessity is an open question tied to the PERFORMS follow-up above.

Test plan

• pytest -n auto -v alchemiscale/tests/integration/storage/test_statestore.py -k merge_networks
• pytest -n auto -v alchemiscale/tests/integration/interface/test_api.py -k merge_networks
• pytest -n auto -v alchemiscale/tests/integration/interface/client/test_client.py -k merge_networks
• black --check --diff alchemiscale
• mypy alchemiscale
• Confirm whether test_merge_networks_preserves_tasks_and_results reveals the suspected missing PERFORMS wiring; open a follow-up if so.

🤖 Generated with Claude Code

[dotsdl]

Thanks for the careful review. Pushed d0bf4ec addressing the feedback.

Blocking

• User story: Send a single simulation to F@H #1 Missing PERFORMS edge — fixed in _TransformationData.to_subgraph. The cloned Task is now wired to tf_node with a PERFORMS relationship in the same iteration that creates it. This also retires the open question about subchain_cache: tf_node is now meaningful as the PERFORMS anchor, so the cache stays.
• [user story] Retrospective analysis of alchemical decisions #2 Cloned tasks not actioned to the new TaskHub — documented as intentional in both the store-level docstring and the client docstring, with the remediation path spelled out (call action_tasks against the merged network's TaskHub after the merge if you want errored tasks back in the queue). Holding behavior change for a follow-up.

Should-fix

• Alternate methods of calculating free energies on GROMACS other than nonequilibrium methods #3 O(N²) dedup — switched to dict[GufeKey, _TransformationData] keyed on transformation.key. Insertion order is preserved by the dict itself; transformation_data.values() replaces the prior list in downstream iteration.
• [user story] absolute binding free energies on a large scale #4 state parameter — threaded through Neo4jStore.merge_networks → POST /networks/merge → AlchemiscaleClient.merge_networks, defaulting to NetworkStateEnum.active. Added a parametrized client test test_merge_networks_respects_state over {active, inactive}.

Nits picked up

• /networks/merge is now async def for consistency with create_network.
• Improved the KeyError handler to collect all missing source ScopedKeys before raising, instead of reporting only the first failure.
• Added a one-line comment at the zip(database_keys, transformations) site pointing at decode_subchains's yield-order guarantee.
• Dropped the unused network_tyk2 fixture from test_merge_networks_bad_scope and test_merge_networks_bad_source_scope.

Deferred

• update_task_trees staticmethod → module-level helper: skipping for this PR to keep the diff focused. Easy follow-up.
• Stray f"..." strings without placeholders in test_statestore.py: these are in the original contributor's code; cleaning them up here would muddy the diff. Happy to do it in a follow-up cosmetic PR.

Sanity check the reviewer asked for

Static analysis confirms the PERFORMS edge is now emitted inside the per-task loop with the correct direction (Task → Transformation) and scope properties. Will report back once I've run pytest -n auto alchemiscale/tests/integration -k merge_networks in an env with grolt.