Epic: Migrate copick-web to OME-Zarr 0.5 and Zarr v3

[uermel]

Objective

Migrate copick-web to the published copick 2.0 alpha contract so the application reads both legacy OME-Zarr 0.4 / Zarr v2 and OME-Zarr 0.5 / Zarr v3, including canonical sharded output, without regressing viewer behavior or remote-backend efficiency.

Core prerequisite: copick-v2.0.0-alpha.1 at 5b3aff2ae4bf9bcf85b4a1d4132205640171f85b.

Target branch: v2.0.

Related migrations:

• copick-utils Epic #84
• copick-torch Epic #137
• copick-shared-ui Epic #53
• copick organization migration project

Locked approach

• Establish deterministic fixtures and always-reporting CI gates before runtime changes.
• Replace the server's synchronous mapping assumption with the async Zarr 3 Store contract.
• Preserve existing URLs while adding correct HEAD and single-range HTTP semantics.
• Prove the current Idetik/Zarrita lock against OME-Zarr 0.4/0.5 and Zarr v2/v3 before considering a viewer dependency upgrade.
• Validate local, S3, SSH, and ML Croissant end to end; record SMB as optional until core promotes it.
• Release server and client together via GitHub prereleases and versioned GHCR images. Do not establish PyPI/npm publishing.
• Protect main and v2.0; add required status contexts only after the test-gate issue creates stable non-skipped jobs.

Workstreams

• Establish the copick-web migration test and fixture gate #17 — Establish the copick-web migration test and fixture gate
• Adopt copick 2.0 alpha and an async range-capable Zarr proxy #14 — Adopt copick 2.0 alpha and an async range-capable Zarr proxy
• Validate OME-Zarr 0.5 rendering and client behavior #16 — Validate OME-Zarr 0.5 rendering and client behavior
• Validate copick-web backends, containers, and range-read performance #15 — Validate copick-web backends, containers, and range-read performance
• Configure copick-web alpha releases and coordinated 2.0 promotion #18 — Configure copick-web alpha releases and coordinated 2.0 promotion

Definition of done

• Legacy OME-Zarr 0.4 / Zarr v2 and OME-Zarr 0.5 / Zarr v3 render in the same build.
• Canonical sharded integer and shuffled floating-point arrays decode to fixture checksums.
• GET, HEAD, and byte ranges are correct and range reads remain bounded through the Zarr store.
• Tomogram, segmentation, channel, contrast, orientation, and pick behavior retain parity.
• Python 3.11-3.14 and Node 20.19/22 gates pass with nonzero test collection.
• Local, S3, SSH, and ML Croissant backend gates and pinned production-container smoke tests pass.
• Exact alpha artifacts pass a post-release smoke test; alpha images never move latest.
• Server and client promote together to stable 2.0.0 with deployment and rollback documentation.

Artifact policy

The authoritative artifacts are GitHub release/prerelease records and the ghcr.io/copick/copick-web-server / ghcr.io/copick/copick-web-client images. PyPI and npm publication are out of scope.

[uermel]

Implementation is in review in PR #19 at head ccf2787. All PR checks are green: Python 3.11-3.14, Node 20.19/22, server/client/migration behavior gates, both production-image smoke jobs, container behavior gate, lint, and conventional title. Remaining release gates are tracked in the open workstreams: external S3/SSH/ML Croissant validation, first alpha publication, stable promotion, and required-check enforcement once contexts can report on both protected branches.