Public decimal→word parse API to mirror the 0.9.0 emit surface, before the 1.x freeze

[espg]

Ask: export a public, numpy-only parse counterpart to the decimal emit surface added for #104 — e.g. a scalar mortie.decimal_to_word(s) (and optionally a vectorized inverse of to_decimal) — ideally before the 1.x spec freeze (#48 / #62), since downstream code is starting to depend on it.

Context: zagg adopted decimal morton strings as the external/path form for shard ids (englacial/zagg#199, PR englacial/zagg#205), per the frozen convention. The emit direction is fully public in 0.9.0: decimal_repr() (mortie/morton_index.py:500), to_decimal() (:514), hive_path() (:548). The parse direction is not:

• _decimal_to_word (:35) does exactly the right thing — scalar, numpy-only, raises on malformed input — but is private, so zagg's parse boundary (zagg.grids.morton.morton_word) currently reaches into mortie.morton_index._decimal_to_word, which will break silently on any internal rename.
• The public alternative, MortonIndexArray.from_hive_path (:570), is a path-parsing classmethod on the pandas ExtensionArray: using it as a scalar decimal→word parse means a pandas import and ExtensionArray construction per call, in hot paths (per-shard key parsing) that are otherwise pure numpy.

Round-trip symmetry (word → decimal → word) is now load-bearing downstream — zarr store leaf paths, status-channel keys, and CLI shard selection in zagg all parse decimal ids back to packed words.

Small doc rider: while exporting, it would be worth documenting the order-29 point/area non-injectivity caveat on the parse side (surfaced during review of englacial/zagg#205) so parse-side users know decimal ids at the terminal order don't distinguish the two.

[espg]

🤖 from Claude

Plan for the public decimal→word parse surface. Grounded in current main: the parse logic already exists as the private scalar mortie.morton_index._decimal_to_word (morton_index.py:35) — numpy-only, raises on malformed input, internally packs via rust_mi_from_nested. The emit side is fully public and vectorized: decimal_repr() / to_decimal() (morton_index.py:499/:513; to_decimal → a "<U31" numpy array) and the scalar MortonIndexScalar.__str__ (:81). There is no vectorized Rust parse binding today (only the emit-side rust_mi_decimal_repr); _decimal_to_word is a per-element Python loop over from_nested. So the work is (i) promote the scalar to public, (ii) decide whether to add a vectorized inverse and where it lives.

Acceptance criteria

• Public mortie.decimal_to_word(s) — numpy-only (importing/calling it triggers no pandas import), raises ValueError on malformed input, and round-trips word → to_decimal → decimal_to_word → word as identity for every non-point word, orders 0–29.
• The order-29 point/area non-injectivity is documented on the parse side: an order-29 decimal parses to the area word (the point flag is not part of the decimal form), so point words do not round-trip — pinned by a test, not just prose.
• If a vectorized inverse is added, it matches the scalar elementwise and mirrors to_decimal (string array → uint64 word array).
• zagg's parse boundary imports a public name instead of reaching into morton_index._decimal_to_word.

Phases

• Phase 1 — public scalar. Promote _decimal_to_word → public decimal_to_word in morton_index.py; keep _decimal_to_word as a thin private alias so from_hive_path and any current importer keep working. Add it to that module's __all__ and re-export from mortie/__init__.py. Tests: malformed inputs (bad base digit, a 0 digit, over-order-29, non-ascii), round-trip over the existing golden decimal fixtures, and a sys.modules-based assertion that the call path does not import pandas.
• Phase 2 — vectorized inverse (pending the fork in open question 2). Mirror to_decimal: a string-array → uint64-array parse. Either a new rust_mi_from_decimal binding + cargo test, or a numpy-only Python wrapper over the scalar.
• Phase 3 — doc rider. The order-29 point/area caveat on the parse side, in the docstring and cross-linked into the spec page (v1.0 docs: specification & conventions page (bit-layout + resolution/Δ table + frozen-convention statement) #62, which already owns the decimal-repr conventions). No code surface beyond docstrings.

Files likely touched

• mortie/morton_index.py — rename/alias, __all__, optional from_decimal classmethod, docstrings.
• mortie/__init__.py — export decimal_to_word (+ the vectorized name if added).
• src_rust/src/lib.rs (+ src_rust/src/decimal_morton.rs) — only if Phase 2 takes the Rust-binding route.
• mortie/tests/ — round-trip, malformed, non-injectivity, numpy-only-import tests.
• Docs (v1.0 docs: specification & conventions page (bit-layout + resolution/Δ table + frozen-convention statement) #62 rider).

Open questions (answerable in one pass)

1. Return type of the scalar. Plain Python int (the packed word), np.uint64, or a MortonIndexScalar (which round-trips display back to the decimal string)? I lean np.uint64 — it is the word, stays numpy-native for hot loops, and callers who want display can wrap it in MortonIndexScalar.
2. Vectorized inverse — add it, and how? (a) a vectorized Rust rust_mi_from_decimal mirroring the emit-side to_decimal_repr — fast and symmetric, but new Rust + cargo test/clippy; (b) a numpy-only Python wrapper looping the scalar — simpler, adequate unless parse is genuinely hot. The issue calls the round-trip "load-bearing" in per-shard hot paths, which argues for (a). This is the one real scope fork. Recommend (a).
3. Surface shape. Keep the core numpy-only (a module-level decimal_to_word + a vectorized decimals_to_words), and additionally expose a MortonIndexArray.from_decimal(strings) classmethod mirroring .to_decimal() for pandas users? Or module functions only? The numpy-only path must exist regardless (avoiding a pandas import per call is the issue's whole point); the classmethod is optional sugar.
4. Naming. decimal_to_word / decimals_to_words (mirrors word/words), or from_decimal (mirrors to_decimal)? Confirm the pair to freeze — this lands in the 1.x public surface (Version 1.0 Sweep (Follow up to new morton datatype) #48/v1.0 docs: specification & conventions page (bit-layout + resolution/Δ table + frozen-convention statement) #62), so the name is a freeze commitment.
5. _decimal_to_word back-compat. zagg currently imports the private name. Keep the private alias indefinitely, or drop it once zagg moves to the public name (coordinated, since both repos are yours)?

Once (1)–(4) are settled I can open the implement PR on claude/114-decimal-parse. Marking waiting on those answers.

---

Generated by Claude Code

[espg]

...can this be closed, or is it still actionable?

[espg]

🤖 from Claude

Still actionable — nothing has shipped yet. On current main the parse direction is still private: _decimal_to_word (mortie/morton_index.py:35) is not in any __all__, and zagg's parse boundary still reaches into that private name, which is exactly the breakage-on-rename risk this issue is about. So the public surface it asks for does not exist.

The plan comment above left five questions open and I marked it waiting; you never had to answer them, so here is a single recommended shape you can green-light (or amend) in one pass, since the name is a 1.x freeze commitment:

1. Promote _decimal_to_word → public decimal_to_word(s) -> np.uint64 (numpy-only, no pandas import, raises ValueError on malformed input), add to __all__ + re-export from mortie/__init__.py; keep _decimal_to_word as a thin private alias so nothing in-tree (or in zagg) breaks on the rename.
2. Vectorized inverse decimals_to_words(arr) -> uint64[] mirroring to_decimal — the issue calls the round-trip load-bearing in per-shard hot paths, so a Rust binding (symmetric with the emit-side rust_mi_decimal_repr) is the honest choice over a Python loop.
3. Doc rider: pin the order-29 point/area non-injectivity on the parse side (an unmarked order-29 decimal parses to the area word; the p-marked form round-trips to the point word) with a test, cross-linked into the spec page (v1.0 docs: specification & conventions page (bit-layout + resolution/Δ table + frozen-convention statement) #62).

If that shape and the names decimal_to_word / decimals_to_words are acceptable, say the word and I'll open the implement PR on claude/114-decimal-parse. Leaving waiting on your pick of the naming pair (the one real freeze decision here).

---

Generated by Claude Code