Feature: Basic H3 Cell-Mode Support in SpatialLite

[LKabrt]

Summary

Add foundational support for the H3 geospatial index in SpatialLite, limited to H3 cell mode and a focused subset of APIs. The implementation should be native C# and aligned with .NET design conventions while maintaining behavioral compatibility with the upstream H3 reference implementation.

Reference documentation: https://h3geo.org/docs
Reference implementation (C): https://github.com/uber/h3

Problem Statement

SpatialLite currently has no built-in H3 support. Users needing H3 indexing must rely on external libraries or custom integrations, which creates friction and inconsistent behavior across projects.

Goals

• Introduce first-class H3 support for cell mode.
• Provide a predictable and idiomatic .NET API surface.
• Match H3 reference behavior for the selected feature subset.
• Establish a compatibility baseline that enables future H3 expansion.

Scope (Initial Subset)

The initial release covers the following operations:

• LatLngToCell
• CellToBoundary
• GetResolution
• StringToH3
• H3ToString
• IsValidCell
• CellToParent
• CellToChildren

Functional Requirements

• Support only H3 index cell mode for this feature.
• Input and output behavior for the scoped operations should be compatible with upstream H3 behavior.
• Validation behavior should mirror reference expectations for valid and invalid cell indexes.
• Hierarchical functions must preserve expected parent/child semantics for cell indexes.

Compatibility Requirements

• Use the upstream H3 C implementation as the behavioral reference.
• Use upstream test assets from uber/h3/tests as compatibility data input.
• Compatibility verification should prioritize deterministic parity for the scoped APIs.

.NET API Design Requirements

The API must feel native to .NET rather than a direct C-style port:

• Avoid exposing the feature as a single static utility class.
• Prefer clear domain abstractions, strong typing, and discoverable naming.
• Follow existing SpatialLite architecture and coding conventions.
• Keep extensibility in mind for future H3 capabilities without breaking changes.

Non-Goals (Out of Scope)

• Any H3 indexing modes other than cell mode.
• Full H3 surface area (e.g., traversal, compaction, region fill, directed edges, vertex mode).
• Performance optimization work beyond what is necessary for correctness and compatibility.

Acceptance Criteria

• SpatialLite exposes the scoped H3 cell-mode operations listed above.
• Public API shape is idiomatic for a .NET library and consistent with SpatialLite design patterns.
• Behavior for scoped APIs is verified against upstream H3 reference expectations using upstream test data.
• Documentation clearly states supported H3 subset, assumptions, and explicit non-goals.

Risks and Considerations

• Exact compatibility requires careful handling of H3-specific edge cases (e.g., pentagon behavior and index validation rules).
• Upstream tests include broader H3 scenarios; only relevant cell-mode subset should be applied to this feature while preserving future expansion paths.