Adopt zagg#299 template-hash leaf naming (coordinated breaking change)

[espg]

🤖 from Claude

Tracking issue for the moczarr side of englacial/zagg#299 (template-hash leaf naming, multi-product hive stores — a breaking store change, pre-1.0 per the zagg#262 rationale). Opened per the phase-6 plan on #1 (item 5): the coordination zagg#299 asks for ("coordinate the rename with moczarr before its vectors harden") needs a home on this side.

Blocked on zagg landing englacial/zagg#299. Nothing here moves until the zagg-side decisions (per-product manifest shape, sidecar shard_key validation, hash truncation length) are final and the writer ships.

Blast radius in moczarr (mirrors zagg#299's list)

• Leaf basename {full_id}.zarr → {hash}.zarr (windowed: {full_id}_{window}.zarr → {hash}_{window}.zarr). The morton id survives only as the digit-tree path; the basename becomes product identity.
• convention.py surface: check_node_invariant (asserts full_id == head + digits via the basename — loses its self-validation; placement validation moves to the sidecar's recorded shard_key), split_leaf_name, and leaf_path all assume the current basename grammar.
• Per-product manifests: morton_hive.json becomes per-product ({hash}.morton_hive.json or a products map — open question on zagg#299); moczarr's manifest/coverage readers follow whichever shape zagg lands.
• SERC fixture + golden vectors regenerate: tests/data fixture stores and the read-side golden parity vectors are pinned to {full_id}.zarr basenames and must be regenerated from the flipped zagg writer in the same PR.
• One coordinated breaking PR here, landed in lockstep with (immediately after) the zagg writer flip — not piecemeal.

What is already insulated

Phase 6 (the cross-resolution join, #1) is deliberately basename-agnostic: parent_cells/join_coarse operate on coordinate values, and phase-6 tests go through open_hive outputs only — never raw leaf paths or basenames — so the join layer needs no changes when the rename lands.

Refs #1 (phase-6 plan, item 5). Blocked by englacial/zagg#299.

[espg]

🤖 from Claude

Requirement added from the updated zagg#299/#300 discussion (espg-directed): path_grouping

The zagg-side ratification (#300 thread, decisions 1/3; #299 thread) adds a path_grouping field to morton_hive.json in the #299 window: an int (or explicit digit-chunking list) controlling how many morton digits form each path component. Existing stores are retroactively path_grouping: 1; new stores default 1; a future move to grouped prefixes is a default flip, not a schema change.

Binding constraint for this issue's implementation (espg, verbatim intent): moczarr lands "chunk the digit string per path_grouping" as the ONLY path-construction code path — never a hardcoded one-digit assumption with a parameter bolted on later. Concretely:

• convention.leaf_path / check_node_invariant / the walk's digit-child classification all parameterize on the manifest's path_grouping — the one-digit case is path_grouping=1, not a separate branch. (Readers already fetch the manifest before any path work — they need shard_order — so the grouping is always in hand; D10 unchanged.)
• Note leaf_path currently delegates to mortie's hive_path (one-digit convention owner) — the grouped generalization either lands mortie-side (preferred: the spec home, v1.0 docs: specification & conventions page (bit-layout + resolution/Δ table + frozen-convention statement) mortie#62) or moczarr chunks the decimal itself; coordinate with the mortie spec update in the same window.
• Golden vectors: include at least one fixture store with path_grouping: 3 in the parity vectors, even while zagg's default is 1 — so the generic path is exercised, not theoretically supported. (The generator gains a knob; the walker/node-invariant tests run against both groupings.)
• Same requirement flows to gridlook Phase 6's TS "moczarr-lite" (noted on Plan: shard-vector + output-grid globe viewer, packaged for JupyterHub (cryocloud) gridlook#1): its path arithmetic reads path_grouping from the manifest from day one.
• Also from the #300 ratifications, relevant to reader posture here: full enumeration is out-of-contract — readers are MOC-first always; recursive LISTs are audit tooling. moczarr's walk_leaves stays (it's the D9 fallback + audit surface) but must generalize its child classification to grouped components.

Still blocked on zagg landing #299; this comment pins the scope so the implementing agent inherits it whole.

[espg]

🤖 from Claude

Scope extension proposal from zagg-side planning: zagg's morton-only writer flip (zagg#262 D16, implementation issue zagg#304) is now slated for the same break window as the zagg#299 leaf rename this issue tracks. Concretely, the post-break fixture stores will differ from today's in two ways at once — leaf basename {template_hash}.zarr (zagg#299) and no stored cell_ids with dggs attrs name: "morton" / coordinate: "morton" (zagg#262). Suggest this issue's golden-vector regeneration cover both in one pass, so parity vectors churn once. The fabrication layer from PR #7 is what makes the second half free reader-side. One request from that work: implement path construction generically from the manifest's forthcoming path_grouping field (zagg#300 discussion — retroactively 1 for existing stores) rather than assuming one digit per level, ideally with one path_grouping: 3 fixture exercised even while zagg's default stays 1.

[espg]

🤖 from Claude

Correction to my earlier scope-extension comment: the zagg#299 leaf-basename rename is superseded — espg ratified a hash-first product root design instead ({store_root}/{hash}/ with each product subtree a complete, unmodified morton-hive store; trade study on zagg PR #306, scope revision on zagg#299). Consequences here: no golden-vector regeneration for naming — open_hive on a product root works unchanged, and this issue's churn reduces to root-level product discovery (distinguish a bare store from a product directory by root content: manifest vs {hash}.yaml entries). The zagg#262 writer flip (morton-only, no stored cell_ids) remains the one breaking change to coordinate. The path_grouping manifest-field request from my earlier comment stands.

[espg]

🤖 from Claude

Second correction as the zagg-side design settled (zagg PR #306 phase 5, D19 rev 2): product roots are now named, not hash-named — {store_root}/{name}/ with the semantic hash demoted to a frozen manifest key (semantic_hash) and the canonical core at {name}/aggregation.yaml. For this issue that's a simplification again: product discovery = list the store root and read each {name}/morton_hive.json — no {hash}.yaml registry translation at all. Also heads-up for the mixed-order guard swap tracked in #8: zagg D24 makes regionally mixed cell orders a first-class store state (per-leaf truth in morton words + MOC), so the guard swap becomes load-bearing once mortie#116 lands.

[espg]

🤖 from Claude

The one remaining breaking store change is now in flight: englacial/zagg PR #314 (zagg#304, the D16 morton-only writer flip). When it lands, moczarr's golden parity vectors regenerate once, for this change alone:

1. cell_ids absence — zagg leaves stop carrying the NESTED cell_ids array; morton (packed u64 words) is the only stored cell coordinate. NESTED is fabricated at read (the PR cell_ids fabrication layer — the zagg#262 gate (issue #1) #7 layer — already merged here, which is why this is unblocked).
2. New convention attrs — the leaf group's dggs block becomes name: "morton", coordinate: "morton", plus the O10 resolution: "exact" | "point" discriminator (zagg#305 ruling: exact for grid-derived cells — all zagg outputs; point reserved for order-29 raw lat/lon ids, the only kind the 29→24 clip applies to). The zarr_conventions list gains the self-declared morton convention entry (permanent UUID 3e22156d-ea9e-4e01-95fe-e3809a4b41e7). Normative spec: espg/mortie PR #118 (mortie#62, docs/specification.md §4–§5). A store with the OLD name: "healpix" + indexing_scheme: "morton" form should hard-reject with a diagnostic — that shape is exactly the scheme-blind misread hazard D16 retired.

There is no naming churn in this window (per the two corrections above — D19 named product roots are additive; D23 /3 leaf naming is spec-string-discriminated). A transition escape hatch (emit_cell_ids: true) can keep legacy-shaped demo stores writable until the gridlook morton path lands; hatch stores still carry the new attrs.

Suggested sequencing: regenerate goldens against a zagg store written from the PR #314 branch once its phase 2 (default flip) lands; the PR thread will note when that phase is pushed.

[espg]

🤖 from Claude

Correction to the attrs half of my coordination comment above (espg final ruling, 2026-07-21, superseding the O10 discriminator design): there is no resolution field. Point-vs-area kind is carried by the packed-word encoding itself — suffix 0..=47 = area word, an exact cell at every order incl. 29; 48..=63 = order-29 point — so readers never consult a declaration. What PR englacial/zagg#314 now emits: dggs: {name: "morton", coordinate: "morton", refinement_level, …} plus the two-entry zarr_conventions list (self-declared UUID 3e22156d-ea9e-4e01-95fe-e3809a4b41e7 unchanged). Also relevant to readers here:

• the order-29 decimal parse tie-break is normative on the mortie spec page §4 (unmarked string ⇒ area word), and the render grammar gained an optional kind suffix p on point ids (decimal repr kind suffix: emit p for point ids, accept on parse (spec §2/§4) mortie#120, PR Decimal kind suffix p for point ids (issue #120) mortie#121) — paths never carry it, so open_hive/path parsing is unaffected;
• the 29→24 clip is a viewer-side transient cast, not store/encoding semantics — moczarr should not clip.

The golden-vector regeneration scope is otherwise as stated: cell_ids absence + the (now resolution-free) morton-declared attrs block.

[espg]

🤖 from Claude

Re-scope (espg-approved 2026-07-20): from "coordinated breaking change" to two additive PRs

zagg PR #306's D19 rev 2 landed product roots as named directories ({store_root}/{name}/, each subtree a complete unmodified morton-hive store; the template hash demoted to a semantic_hash manifest key with the canonical core at {name}/aggregation.yaml) — so #299-as-merged is additive. Leaf basenames, the node invariant, D3/D13, the SERC fixture, and every golden vector survive untouched. This issue's original blast-radius list is obsolete; the re-scoped work (bundling espg-approved in-session):

PR-A — "spec-alignment" (correctness against the finalized spec)

1. path_grouping (zagg D21 / mortie spec §6). The manifest field (int, default 1) becomes the ONLY path-construction code path: leaf_path, check_node_invariant, and walk_leaves' child classification chunk the digit string per the manifest — 1 is a value, never a separate branch. Note leaf_path currently delegates to mortie's hive_path (one-digit); either mortie grows the grouped form or moczarr chunks the decimal itself against the spec grammar — resolve during implementation, spec-cited either way. Golden fixtures include a path_grouping: 3 store (generator knob) so the generic path is exercised, per the espg directive recorded above.
2. Point-kind handling per the FINAL mortie spec §1/§4 — the kind is encoding-carried in the word (suffix 48..=63 = order-29 point; area otherwise); there is no resolution attrs field (the earlier attrs-block ruling was deleted in the spec's final revision; zagg O10's entry lags — flagged to espg separately). Work: (a) convention.py decimal grammar grows the terminal-p point marker (legal only on full order-29 strings; paths never carry it; unmarked order-29 parses as area per the §4 tie-break) — accept and emit; (b) the 29→24 clip lands in fabricate.py, keyed on the encoding-carried point kind (mortie kind predicate or suffix mask — probe what PR #118 exposed), replacing the deliberate seam + warning we left: point-kind words clip to order 24 for the NESTED view; genuine order-29 area cells do NOT clip (and stay behind the existing >24 float64 warning); (c) aoi_mask/ranges: document (and test) behavior when point-kind words appear — v1 posture: points are order-29 members like any other for containment; mixed area+point arrays are well-formed per spec.
3. The zarr DGGS convention block (mortie spec §5). name: "morton", coordinate: "morton", and the permanent self-declared convention UUID 3e22156d-ea9e-4e01-95fe-e3809a4b41e7: the [xdggs] layer's decode recognizes the block (via xdggs's "zarr" convention path and/or our decode()), constants exported, tests against writer-flip-shaped attrs so moczarr is correct on day one of zagg's D16 flip.

PR-B — "multi-product + sidecars" (the D19/D20 surface)

4. Product roots: list_products(store_root) (named children carrying manifests; surfaces semantic_hash + aggregation.yaml presence), open_hive(store_root, product="name") sugar (equivalent to opening the subtree — which already works today, pinned by a test), and a pointed error when a multi-product root is opened without product=. Single-product stores unchanged (the degenerate form is explicitly valid per the spec).
5. Stats sidecars (zagg D20/D23, shipped writer-side in zagg PR #307): read {window}.stats.json + the all token; a read_stats() surface returning the per-leaf record (and the rollups when the #300 sweep lands them); O11 verification helper — verify= or verify_arrays() recomputing per-array sha256 over decoded values against the sidecar record. This is also the data source gridlook's #301 cost choropleth consumes.
6. Fixtures: existing SERC fixture stays; ADD a two-product fixture (two named roots under one store, one shared + one distinct product) and stats-sidecar fixtures (zagg-written via #307's path if cheap, else hand-built to the D20 schema with the same golden-parity discipline).

Sequencing + status

PR-A first (it's what makes moczarr correct against stores zagg is about to write); PR-B follows. Both additive — no breaking window, no golden regeneration. Nothing further is actionable on espg for this issue: the bundling is approved, this comment is the plan of record, and implementation proceeds under the standing per-PR review/fold cycle (findings that imply design forks come back to this thread). The old blast-radius body above stands as history; this comment supersedes it.