feat(zarr): warn on stale hand-edited encoding['chunks'] via metadata baseline

[d-v-b]

🤖 AI text below 🤖

Summary

Uses the read-only encoding["zarr_array_metadata"] document (added in the parent PR) as a provenance baseline to warn about stale, hand-edited encoding["chunks"].

On write, if a variable still carries the stored metadata document but its encoding["chunks"] matches neither the source array's chunk shape nor the variable's own current (dask) chunking, it was almost certainly edited by hand and is now stale → DeprecationWarning.

What it deliberately does NOT warn on

• A plain round-trip (read → write unchanged) — encoding["chunks"] still equals the document.
• .chunk(...) — changes the dask chunking but leaves encoding["chunks"] untouched (chunks.py:116-117).
• overwrite_encoded_chunks=True — sets encoding["chunks"] to the variable's current chunking, i.e. consistent with the data being written.

Honest scope note

Fully deprecating any use of the chunks key is not feasible: overwrite_encoded_chunks=True is a legitimate first-party writer of encoding["chunks"], and at write time it's indistinguishable from a hand-edit by value alone. So this scopes the warning to the genuinely stale/inconsistent case (differs from both the source and the data), which is the actual footgun, rather than "any use of the key." encoding is a plain mutable dict, so this drift-vs-baseline check at the consumption boundary is the most reliable signal available without wrapping the dict.

This also generalizes: the same baseline diff could flag user overrides of other derived keys (compressors, fill_value, …).

Testing

• test_encoding_chunks_drift_warns: hand-editing encoding["chunks"] on a round-tripped variable warns.
• test_encoding_chunks_no_drift_no_warn: .chunk(...) then write does not warn.
• Existing test_manual_chunk (which exercises overwrite_encoded_chunks=True) stays green.

Stacked on claude/zarr-metadata-fragment (PR #2).

[This is Claude Code on behalf of Davis Vann Bennett]

🤖 Generated with Claude Code