feat: builtin zarr:, zarr2: and zarr3: URL pipeline adapters

[jhamman]

(not ready for review yet)

Summary

Adds the builtin zarr:, zarr2: and zarr3: URL pipeline adapters from the spec
(schemes/zarr.md), and
makes Group.open / Array.open work with them without passing zarr_format=None (F3).

zarr.open_group("data/|zarr2:", mode="w")
zarr.open_array("file:///data/|zarr2:path/to/array")
zarr.Group.open("s3://bucket/x.zarr|zarr:")   # format auto-detected

• Adapters (src/zarr/storage/_url_adapters/_format.py). The segment body is a path
  within the preceding resource and is joined onto the preceding residual path. zarr2: /
  zarr3: set AdapterResolution.zarr_format; zarr: leaves it None (auto-detect). Every
  other field is carried forward with dataclasses.replace, so a format segment also works as
  an intermediate segment (root|zarr2:a|other:b). A query, a ./.. path segment, or two
  format segments that disagree (|zarr2:|zarr3:) raise URLPipelineError. zarr: after a
  zarr2: keeps the earlier format instead of erasing it.

• Registration (registry.py). The builtins are lazily loaded entry points prepended to
  the zarr.url_adapters pending list in _collect_entrypoints. Importing zarr does not import
  them (tested in a subprocess), and there are no new import cycles. A third-party entry point
  with the same name is ignored with a ZarrUserWarning ("the builtin ... takes precedence").
  An explicit register_url_adapter("zarr3", ...) call still overrides a builtin, silently.
  _collect_entrypoints can be called repeatedly (the test fixtures do) without duplicating
  builtins.

• Adapter-only schemes. zarr, zarr2 and zarr3 are never dispatched as a pipeline
  root. So a string without |, such as zarr3:foo, behaves exactly as it does on main.

• F3. Group.open, Array.open, AsyncGroup.open and AsyncArray.open now default to a
  private "unspecified" sentinel (zarr.core.common._UNSPECIFIED). When the caller does not pass
  a format:

  • a URL pipeline decides: its format segment if there is one, otherwise auto-detection;
  • every other store keeps today's default of 3, so metadata probing for non-pipeline
    callers is unchanged (pinned by test_open_classmethod_default_without_pipeline).

  An explicit zarr_format (including None) behaves as before, and a conflict still raises
  ValueError. The pinned tests in TestZarrFormatMergeInCore are updated.

Depends on

• feat: url-pipeline core — parser, adapter ABC, registry, store hooks #4192 (URL pipeline core). This branch is stacked on feature/url-pipeline-core, so until
  feat: url-pipeline core — parser, adapter ABC, registry, store hooks #4192 merges the diff here includes its commits. Review only the commits after 03ab3b05.

This is PR 1 of a stack. Later PRs: read-only zip:, the file-resource primitive plus a
writable zip:, root semantics/Windows/API polish, and the user guide.

Closes

• Follow-up F3 (Group.open / Array.open default zarr_format=3).
• The zarr2:/zarr3: half of follow-up F9 (builtin adapters, registered through
  _collect_entrypoints).
• Roadmap row Z1.
• Part of Support ZEP 8 URL Syntax #2943.

Decision needed

F3: how Group.open / Array.open choose the default format. This is isolated in the
commit "feat: let URL pipelines pick the format in Group.open / Array.open".

• Implemented: a private sentinel default. Pipelines pick the format (auto-detect when there
  is no format segment). Everything else keeps 3. This adds no probing cost for existing
  callers. One subtlety: a pipeline without a format segment (for example x.zip|zip:, in a
  later PR) auto-detects, while the same store passed as a Store object defaults to 3.
• Alternative A: change the default to None everywhere, like zarr.open_group. This is
  simpler, but every existing Group.open(store) caller would then fetch both v2 and v3
  metadata keys.
• Alternative B: leave the default at 3 and document zarr_format=None for pipelines (as
  in feat: url-pipeline core — parser, adapter ABC, registry, store hooks #4192). This works against zarr2: and the spec's zarr: auto-detection.

zarr: after another format segment. root|zarr2:|zarr: keeps format 2. The
alternative is to have zarr: reset the format to auto-detect, which the strict reading of
"zarr: maps to None" implies. Conflicting explicit segments (|zarr2:|zarr3:) raise.

For reviewers

• Is lazy-loaded builtin entry points, rather than eager register_url_adapter calls at import,
  the right mechanism? It keeps import zarr cheap and reuses the collision handling.
  get_url_adapter gained a small special case so that a pending builtin is dropped silently
  when the scheme was registered explicitly.
• Behavior for strings without | is meant to be unchanged; is_url_pipeline("zarr3:foo") is
  False.

Tests

uv sync --frozen
uv run --frozen ruff check src tests
uv run --frozen mypy src
uv run --frozen --with pytest-examples pytest -n auto tests
pre-commit run --all-files

Full suite: 13009 passed, 1295 skipped, 9 xfailed (baseline on feature/url-pipeline-core: 12930 passed, 1295 skipped, 9 xfailed). ruff, mypy and pre-commit are clean.

New tests are in tests/test_url_pipeline/test_format_adapters.py:

• end-to-end zarr.open, open_group, open_array, create_array, Group.open and
  Array.open with |zarr2:, |zarr3: and |zarr: over local and memory: roots;
• auto-detection of existing v2 and v3 data;
• conflicts between an explicit zarr_format and the segment;
• stacked paths (root|zarr3:a/b) and a format segment used as an intermediate segment;
• every schemes/zarr.md example;
• registration and laziness.

Author attestation

• I am a human, these are my changes, and I have reviewed and understood every change and can explain why each is correct.

TODO

• Add unit tests and/or doctests in docstrings
• Add docstrings and API docs for any new/modified user-facing classes and functions
• New/modified features documented in docs/user-guide/*.md
• Changes documented as a new file in changes/
• GitHub Actions have all passed
• Test coverage is 100% (Codecov passes)

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 98.71795% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.78%. Comparing base (25d390b) to head (37b2f49).

Files with missing lines	Patch %	Lines
src/zarr/storage/_url_pipeline.py	97.36%	3 Missing ⚠️
src/zarr/core/common.py	80.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4476      +/-   ##
==========================================
+ Coverage   94.68%   94.78%   +0.09%     
==========================================
  Files          94       97       +3     
  Lines       13596    13889     +293     
==========================================
+ Hits        12874    13164     +290     
- Misses        722      725       +3     

Files with missing lines	Coverage Δ
src/zarr/abc/url_pipeline.py	100.00% <100.00%> (ø)
src/zarr/api/asynchronous.py	96.55% <100.00%> (+0.08%)	⬆️
src/zarr/api/synchronous.py	95.77% <ø> (ø)
src/zarr/core/array.py	98.40% <100.00%> (+<0.01%)	⬆️
src/zarr/core/group.py	95.69% <100.00%> (+0.01%)	⬆️
src/zarr/errors.py	100.00% <100.00%> (ø)
src/zarr/registry.py	93.53% <100.00%> (+1.77%)	⬆️
src/zarr/storage/__init__.py	100.00% <100.00%> (+5.00%)	⬆️
src/zarr/storage/_common.py	93.96% <100.00%> (+0.93%)	⬆️
src/zarr/storage/_url_adapters/_format.py	100.00% <100.00%> (ø)
... and 2 more

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.