Add AlchemicalArchive extraction

[ianmkenney]

closes #246

[dotsdl]

Awaiting new gufe release featuring AlchemicalArchive before we merge.

[dotsdl]

@ianmkenney would you like me to continue on this one? Otherwise happy to leave it to you!

[ianmkenney]

@dotsdl you can take over if you'd like

[dotsdl]

Can do! Thanks for all your work on this! Will ask you for a review once I'm finished!

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.81%. Comparing base (829532e) to head (8be54a3).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #486      +/-   ##
==========================================
+ Coverage   80.54%   80.81%   +0.27%     
==========================================
  Files          31       31              
  Lines        4877     4916      +39     
==========================================
+ Hits         3928     3973      +45     
+ Misses        949      943       -6     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[dotsdl]

Design note: client-side archive assembly

This PR builds AlchemicalArchive extracts client-side (AlchemiscaleClient.get_network_archive / get_network_archives), composing existing retrieval methods, rather than adding a server-side endpoint. The original [DNM] draft sketched a /bulk/networks/archive endpoint; we removed it and reimplemented on the client. Rationale and tradeoffs:

Why client-side

• API worker memory. An archive is inherently bulk: it pulls every successful ProtocolDAGResult (the large objects in the system, backed by S3) for every Transformation in a network and serializes them into one object. Doing that server-side forces a shared API worker to hold the entire result set in memory for a single request. The workers are sized for many small, concurrent request/response cycles — archive generation is the opposite shape (few, huge, bursty). Supporting it server-side would mean provisioning every worker for a peak that is idle almost all the time, i.e. a large, near-permanent over-provision.
• No new API-side bottleneck. A long-lived, memory-heavy request risks head-of-line blocking for all other users of that worker. Client-side, the weight lands in the user's own process, where a big archive is their RAM, not the server's.
• Reuse of tested machinery. Assembly is just AlchemicalNetwork + per-Transformation ProtocolDAGResults + optional metadata. The client already has cached, parallelized retrieval for exactly those pieces, so there is nothing to reimplement server-side. AlchemicalArchive construction is gufe logic that runs identically on either side, so centralizing it buys little.
• Smaller API surface. No new endpoint to authorize, scope-check, version, and maintain.

Tradeoffs accepted

• More round trips. Client-side assembly means N per-transformation fetches instead of one request. Mitigated by using get_network_results, which fans the ProtocolDAGResult retrieval out across processes, so the dominant cost is parallel rather than serial. Acceptable for an infrequent, inherently-bulk export operation.
• When an endpoint would earn its keep: a concrete need the client can't meet — e.g. server-mediated archival for clients that cannot hold the full result set. No such need today; if one arises, a streaming/paginated endpoint can be added without disturbing this client API.

Correctness note

Results are joined to Transformations via their authoritative server-side ScopedKeys (from get_network_results / get_network_transformations), then each Transformation is fetched by that ScopedKey. We deliberately do not reconstruct a ScopedKey from a freshly-deserialized Transformation's GufeKey: a ScopedKey carries the ingestion-time gufe_key, but a GufeTokenizable deserialized later may recompute a different GufeKey if gufe tokenization has changed since ingestion — so a key-reconstructed join can silently drop results rather than error.

[dotsdl]

I'm happy with this! Thanks for the initial work on this @ianmkenney!