[d-v-b]

🤖 AI text below 🤖

Agent summary

Breaking: to_key_value takes a writer instead of an indent keyword. A JSONWriter owns how a document becomes JSON bytes: it holds the settings (indent, sort_keys, ensure_ascii, trailing_newline), and its encode method does the writing. to_key_value also accepts a plain mapping of the settings, so to_key_value(indent=2) becomes to_key_value({"indent": 2}), with no import.

• JSONWriter is a final, frozen dataclass in zarr_metadata.model._json_writer, exported from zarr_metadata and zarr_metadata.model. encode holds every choice about the bytes: the separators of Python's json module, non-finite numbers written as bare tokens (as zarr-python writes attributes), and lone surrogates written as escapes when ensure_ascii is off. The private dump_store_json helper is gone, so nothing else writes store JSON.
• JSONWriterSchema is the closed TypedDict of the settings, every one optional. JSONWriterLike = JSONWriter | JSONWriterSchema is what each model's to_key_value(writer=...) accepts. JSONWriter.from_dict turns either into a writer (a writer passes through), and to_dict goes back.
• The defaults are those of json.dumps, which the models already used, so a bare to_key_value() writes the same bytes as before.
• A setting that json.dumps would accept but misread raises when the writer is built: indent=True (read as 1), a negative indent (read as 0), or a string indent that is not JSON whitespace (written verbatim, giving invalid JSON). A mapping key that is not a setting raises TypeError, so a misspelled setting is not ignored.
• docs/models.md gains a "Writing store bytes" section with a tested example.

tests/model/test_json_writer.py checks, for all five model types and a range of writers given both as JSONWriter and as mappings, that each key's bytes are what json.dumps writes under the same settings, and that the store reads back to an equal model. Each refused value has its own test.

The design moved from an earlier JSONWriterConfig settings object, which a separate private function read, to one object that both holds the settings and encodes, and accepts a mapping so callers need not import it. The agent rebased onto main as one commit and had a separate agent review the redesign. That review found no correctness bugs, and its two actionable points (subclasses passing through from_dict, and gaps in the success cases) are fixed here.

Follow-up elsewhere

The ArrayIO branch (claude/arrayio-lazy-metadata-48d8e5, fork drafts #419/#420) calls to_key_value(indent=zarr_config.get("json_indent")) in store_metadata. Once this lands, that call becomes to_key_value({"indent": zarr_config.get("json_indent")}). This PR does not touch that branch.

🤖 Generated with Claude Code