Conversion Class and Cross-System Guardrails

Three guardrails keep a conversion honest at the wire. Each is enforced by the live tools, not just documented: a conversion_class on every output, a geo_cell_system_conflict rejection for cross-system overlays, and a verbatim echo of the accepted request.

conversion_class — execution vs analysis/planning

Every conversion output declares a conversion_class:

execution

A deterministic partition or containment — center, full, inscribed, equal_area, an S2 point map. Non-overlapping, so it can be trafficked and measured without double-counting.

analysis_planning

An overlapping or expansive approximation — circumscribed, intersect, threshold, an S2/H3 cover. Fit for sizing and planning; NOT fit for execution, because the overlap double-counts audience.

The buyer asserts the class at trafficking time; the implicit default is execution. The seller enforces, and never silently degrades: asserting execution for an analysis-only mode returns a structured conversion_class_conflict naming the mode and its true class, with a correction — choose an execution mode, or assert analysis_planning. The class actually applied travels in the output as provenance, so a downstream reader always knows which kind of geometry it received.

Cross-system overlays MUST reject

An overlay — any set operation combining cell sets — must stay within one cell system. Within a single grid, normalize-then-subtract is exact algebra; across grids it is geometry, with quantified overreach (see the measured H3 ↔ S2 round trip). Mixing systems in one overlay is therefore a structural error, not a tolerance to be tuned: the H3 set tools reject an input that mixes systems with a structured geo_cell_system_conflict that names the detected_systems.

error code

geo_cell_system_conflict

names

detected_systems — every cell system found in the input (e.g. [h3, s2])

remedy

reconcile through a declared cross-system crosswalk (e.g. s2_to_h3) BEFORE combining — never inside the set operation.

The rule is level-agnostic and direction-agnostic: it is the same reason a subtraction of a postal set from a cell set has to go through a declared crosswalk first. Conversion across systems is a first-class, declared step with its own provenance — never an implicit coercion hidden inside an overlay.

The accepted-state echo is verbatim

When a tool echoes the request it accepted, it echoes it exactly as given — no sort, no dedup, no compaction, no reordering. The requested block on h3_to_polygon, h3_compact, and h3_uncompact returns the input cell list byte-for-byte; the computed result lives in a separate field.

This matters because a normalized echo is itself a silent transform: if the echo were compacted to parents or sorted, a client comparing "what I sent" to "what was accepted" would see a difference the server introduced and could not distinguish it from one the client made. The only echo that lets a client verify round-trip integrity is a verbatim one — the accepted state is reported, never rewritten.