Skip to content

v1.0 docs: specification & conventions page (bit-layout + resolution/Δ table + frozen-convention statement) #62

Description

@espg

🤖 from Claude

Sub-issue of #48 (v1.0 sweep), Tier-2 docs.

Scope

The user-facing spec that the 1.x stability contract points at:

  • Bit-layout of the packed-u64 morton index ([4-bit prefix | 54-bit body | 6-bit suffix], base-cell prefix, 27×2-bit body, 6-bit suffix carrying orders 0/28/29) — sourced from src_rust/src/decimal_morton.rs module docs.
  • Resolution / Δ table mapping order 0–29 → HEALPix nside, approximate cell edge length / area (the README "resolution table" espg called for).
  • Conventions: unsigned packed storage, the decimal string as a render-only repr (signed repr kept per the packed-u64 migration (Option A) + norm2mort consolidation #58 design record), Z-order = raw-word sort, base-cell prefix base_id + 1.
  • An explicit "frozen for 1.x" statement of what the contract guarantees (order 0–29, indexing convention immutable within a major version).

Acceptance criteria

A markdown spec page (under docs/), linked from the README; resolution table generated from order2res so it can't drift.

Refs #48.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions