Skip to content

RFC: Cell Interoperability and Execution Conversion — companion to #5969 #6013

Description

@EvgenyAndroid

Status: Filed
Companion to: #5969 (geo_cells / geo_cells_exclude targeting)
Sibling companion: Cell-grain delivery reporting (filed alongside this issue — cross-referenced below once both are up)
Filed by: @EvgenyAndroid, in collaboration with @nwoodman-spec
Primary author: Nathan Woodman — the analysis, design, and conversion-quality math in this document are his
Target: a PR against static/schemas/source/core/targeting.json, a new cell-system.json, and a docs section


1. Why this exists

RFC #5969 defines the addressable unit. It deliberately does not define what a
seller does when it cannot execute on that unit natively, which is every seller
today. Between a buyer declaring geo_cells and an ecosystem that executes on
administrative areas, market codes, polygons, and point-and-radius targets, there
is a conversion step. That step is not neutral, and if it is left to each
implementer, two conformant sellers handed the same cell set will deliver to
materially different ground.

The WG triage on #5969 named this as decision point X-A versus X-B and the
position taken there was X-B: the wire contract stays "MUST NOT deliver outside
the declared cells", conversion is seller-internal, and the conversion rules file
as a companion. This document is that companion.

X-B is still the right boundary. Nothing here is proposed for the #5969 normative
surface, with one exception noted in section 3, which is a single clarifying
sentence that #5969 already needs on its own terms.

2. Scope

In scope. The vocabulary and the declared parameters for converting between a
cell set and the geometry an execution platform accepts, in both directions; the
quality metrics that make a conversion checkable; the provenance record that has
to survive the chain; and the conformance fixtures that prove an implementation
does what it claims.

Out of scope. Accreditation of any measurement methodology, how any actor
estimates exposure or lift against the unit, which industry bodies participate in
governing it, and any change to how geo_cells itself is declared or validated.
Those are real and they are not this.

3. The one sentence #5969 still needs

Fix 3 binds the delivery obligation: a seller MUST NOT deliver impressions outside
the declared cell set. That obligation is ambiguous while the execution primitive
is a shape derived from the cells rather than the cells themselves, because a
derived shape can extend past the cell boundary.

Proposed addition to Fix 3:

The delivery restriction binds the output footprint, not the seller's
internal representation. A conversion whose executed footprint extends beyond
the declared cell set is non-conformant, regardless of the internal method that
produced it.

That is sufficient for correctness, and it is what makes the contamination case
safe without any containment-mode logic in the RFC. Everything below is
optimization and auditability, which is why it belongs here rather than there.

4. The six geographies

A geographic target reads as one object and is handled as a chain of distinct
objects, each a lossy or lossless transform of the last. Conflating any two of
them is the root cause of most disputes about whether delivery matched intent.

Form What it is
Requested The buyer's ask in the buyer's vocabulary. Frequently an identifier, not a geometry.
Source The geometry actually supplied to represent the ask. Already a choice, already lossy.
Normalized Source geometry validated and reprojected to EPSG:4326: closed rings, correct winding, antimeridian split, holes respected.
Canonical cells A cell set at a stated resolution under a stated containment rule. The interchange form. This is what geo_cells carries.
Executed What the platform actually ran: circles, simplified polygons, or native geo IDs. An approximation of the cell set, never identical to it.
Reported / attributed The geography delivery reporting and outcome attribution actually used. Frequently coarser than execution.

geo_cells standardizes exactly one of these six. The value of standardizing it
is that it gives the other five a common reference. The risk of standardizing only
it is that "we targeted the cells" becomes an unfalsifiable claim covering five
undeclared transforms.

An identifier is never a geometry. Two platforms can both expose an id
labelled zone_4471 and mean different polygons. An id carries no shape, area, or
boundary, only a lookup key into a boundary set the platform controls and can
change without notice.

5. Polygon to cells: declare the containment mode

Converting a source polygon into cells requires a containment rule, and the common
default is center containment, which is a genuine partition but does not cover the
source boundary. A cell whose center sits just outside the polygon is dropped even
when it overlaps.

Four modes should be nameable:

Mode Rule Property
center Cell center falls inside the source polygon. Deterministic single assignment, no double counting. Undercovers the boundary.
full Entire cell boundary lies inside the source polygon. Executed geometry is a strict subset of the ask. Deliberate underreach.
intersect Any positive intersection area. Every point of the source is covered by at least one cell. Overreaches, and cells are not mutually exclusive across adjacent regions.
threshold Intersection area over cell area exceeds a stated fraction. Tunable between the two. Requires the fraction to be declared.

A seller using center and a seller using intersect return different cell sets
for the same source polygon. That difference is invisible unless the mode is
declared:

{
  "system": "h3",
  "resolution": 8,
  "source_geometry": {
    "type": "administrative_area",
    "system": "example_market_codes",
    "version": "2026Q2",
    "values": ["501"]
  },
  "conversion": { "operation": "polygon_to_cells", "containment": "center" }
}

Boundary cells may carry an overlap weight. The weight is an analytical crosswalk
term, not an instruction to deliver a fraction of a cell's impressions, and the
spec should say so explicitly because the ambiguity is expensive:

{ "cell": "882a100d25fffff", "coverage_fraction": 0.63 }

6. Cells to proximity: the circle mode changes the experiment

Where a platform executes on a center and a radius rather than a boundary, a cell
becomes a circle. There are three useful circles and they are not interchangeable.

For a regular hexagon of circumradius R:

Inscribed. Center plus the minimum distance from center to any edge. Sits
fully inside the cell, and adjacent inscribed circles meet at the shared edge
without overlapping, so units stay mutually exclusive. Leaves the corners unserved.

radius        = (sqrt(3)/2) R  ~= 0.8660 R
covered area  = pi / (2 sqrt(3))  ~= 0.9069   (9.31% of the cell unserved)

Circumscribed. Center plus the maximum distance to any vertex. Fully covers
the cell and extends past it, so circles from adjacent cells overlap and create
duplicate eligibility near edges.

radius        = R
circle area   = 2 pi / (3 sqrt(3))  ~= 1.2092   (20.92% larger than the cell)
pairwise overlap = R^2 (pi/3 - sqrt(3)/2)  ~= 6.97% of one cell, per adjacent pair

Equal-area. Circle area equals cell area. Preserves area but guarantees
neither full coverage nor exclusivity, so it should not be the default for
delivery or for experimentation.

{ "operation": "cells_to_proximity", "circle_mode": "inscribed",     "radius_method": "minimum_center_to_boundary_distance" }
{ "operation": "cells_to_proximity", "circle_mode": "circumscribed", "radius_method": "maximum_center_to_vertex_distance" }
{ "operation": "cells_to_proximity", "circle_mode": "equal_area",    "radius_method": "cell_area_equivalent" }

Under the section 3 sentence, circumscribed conversion is non-conformant at the
edge of a declared set, because it delivers into undeclared cells. It remains
legitimate for reach use cases where the declared set is the whole intent and
overshoot is acceptable, which is why it is named rather than banned.

Implementation note. Cells are spherical, not regular planar polygons, and H3
carries twelve pentagons per resolution which break the regular-hexagon ratios
above. Radii must be computed from each actual cell boundary, densified along
every edge rather than sampled at the raw vertices, not read from a
resolution-average table.

7. Reverse conversions

Where a platform cannot execute cells natively, a cell set converts to whatever
that platform does accept:

  • Exact polygon or multipolygon. Deterministic from the cell boundaries.
    Dissolve the set, do not emit per-cell polygons, because platform boundary
    matching is polygon against polygon.
  • Center and radius. Approximate. Must declare the circle mode per section 6.
  • Platform-native identifiers. Approximate and platform dependent. Requires a
    versioned crosswalk, a declared match_threshold, and explicit reporting of
    partial matches and unmatched cells. Omitting an unmatched cell is
    indistinguishable downstream from matching it at zero weight, so unmatched cells
    MUST appear in the output as unmatched.
  • Weighted crosswalk to postal, market, or region inventory. Requires the
    weight basis and the boundary vintage to be declared.

Every reverse conversion is subject to platform constraints that change the
footprint independently of the conversion itself: minimum and maximum radius
floors and ceilings, radius rounding increments, target-count caps, unsupported
polygons, unsupported exclusions, coordinate rounding on ingest, undocumented
deduplication of overlapping entries, and automatic audience expansion. Each of
these has a direction. Coarsening to fit a target-count cap overreaches. Dropping
an unexecutable element underreaches. Both must be attributable to the constraint
that forced them.

8. Inclusion and exclusion

geo_cells_exclude needs a stated combination rule.

effective = union(inclusions) \ union(exclusions)

This is a set operation and it is only well defined when both sides are expressed
as cells at a common resolution. Normalize first, then combine. Performing the
subtraction on raw geometry and converting afterwards produces a result that
varies by geometry library and is not reproducible from the grid alone.

Three behaviors should be normative because each is a live failure mode:

  1. Exclusion wins. A cell in both unions is excluded. There is no
    configuration that reverses this.
  2. An empty effective geography is an explicit state, distinct from "no
    exclusions supplied". A system that conflates them launches against zero
    geography without raising.
  3. A dangling exclusion, one that never intersected any inclusion, changes
    nothing and MUST still be reported, because it almost always indicates the two
    sides were built from misaligned assumptions.

The dangerous case is an exclusion a platform cannot express. The platform drops
it rather than erroring, so reported and executed geography agree with each other
and both disagree with intent. Nothing downstream flags it, because the platform
faithfully executed what it was given. This must be caught before launch by
checking declared exclusion support against the request.

9. Conversion profiles

A conversion is underspecified until the containment rule, resolution policy,
circle mode, and weighting are all stated. Naming a profile makes that one field
instead of four, and forces the consumer to know which guarantees hold.

Profile Containment Circle Guarantee Accepted tradeoff
partition_stable center n/a One deterministic assignment per cell, no double counting Boundary undercoverage
coverage_complete intersect n/a Every point of the source covered by at least one cell Overreach, non-exclusive across regions
measurement_weighted intersect n/a Complete many-to-many overlap record retained Storage, and a weight basis that must be sourced and versioned
experiment_conservative full inscribed Executed geometry is a subset of the intended unit, no spill Deliberate underreach at boundaries and corners
proximity_full_reach n/a circumscribed Complete coverage of every target cell Overlap and duplicate eligibility
platform_limit_optimized intersect circumscribed Result satisfies target-count and radius constraints Coarsening enlarges the footprint
privacy_safe center n/a No cell reported below the configured audience or area floor Resolution degradation and suppression

These are not stages of one pipeline. A single campaign commonly needs several: a
privacy_safe audience definition feeding a proximity_full_reach execution,
measured against a measurement_weighted crosswalk, with an
experiment_conservative subset carved out for a lift study. Naming which profile
governs which stage is what keeps the choices auditable.

10. Quality metrics

A conversion is checkable or it is a claim. Four area ratios, computed on
spherical areas in square metres against EPSG:4326 rings, comparing exactly two
geometries at a time:

coverage_ratio   = area(source ∩ execution) / area(source)
overreach_ratio  = area(execution \ source) / area(source)
underreach_ratio = area(source \ execution) / area(source)
jaccard          = area(source ∩ execution) / area(source ∪ execution)

Plus duplicate_eligibility_area_m2, the sum of individual executed feature areas
minus the area of their union, which is the ground eligible under more than one
target.

Coverage and overreach are not complementary. They do not sum to one and
neither bounds the other. Circumscribing every cell in a region produces a
coverage ratio at or above 0.999 by construction while the overreach ratio is
strictly positive and can exceed 1, meaning the executed geometry is larger than
the entire source. Coverage alone MUST NOT be reported as a proxy for targeting
precision. The complement that does hold is
coverage_ratio + underreach_ratio = 1, by set algebra, for any execution
geometry.

Boundary displacement, the maximum or mean perpendicular distance between source
and executed boundaries, answers how far the edge moved, which no area ratio can.
Counts of cells or targets are reported alongside area metrics and never substitute
for them, since cell count says nothing about area without the resolution.

11. Provenance

Each conversion appends to a record and never overwrites the one before it. The
minimum recoverable at the end of the chain:

  • source CRS, vendor, and boundary vintage, with valid_from and valid_to
  • normalization actions taken, meaning what was repaired
  • cell system, resolution, and containment mode
  • execution approximation mode: which circle, which simplification tolerance,
    which crosswalk vintage, which rounding the platform applied on ingest
  • which inclusions or exclusions were dropped because a platform could not
    express them, and why

Losing any one field converts a checkable claim into an unfalsifiable one.
"Intersect-fill at resolution 8, executed as circumscribed circles rounded to the
platform's radius increment" can be audited. "We targeted the area" cannot.

Boundary vintage deserves its own emphasis. A crosswalk built from a stale
boundary file misassigns cells near any line that has since moved, and that
misassignment is indistinguishable in the data from a correct crosswalk on an
outdated boundary. Recording valid_from and valid_to on every crosswalk, and
refusing to join across a vintage gap, is the only defense.

12. Declared resolution is a joint claim

Discussion on #5969 established that a seller declaring support for very fine
resolutions is making a privacy claim and not only a precision claim. The joint
reading is the load-bearing one. A declared resolution carries two assertions at
once:

  1. I can deliver at this grain.
  2. I have assessed that delivering at this grain is safe in the geographies I
    serve.

These are different competencies and a seller can honestly hold one without the
other. They also pull in opposite directions on the same control, since finer is
more precise and less private, which makes a single declared value a claim about a
tradeoff rather than a precision specification with a privacy note attached.

This is why the provenance in section 11 is required rather than advisory. A
conversion that changes effective grain, a circumscribed circle overshooting the
cell or a crosswalk landing on a different footprint entirely, falsifies both
assertions at once. It degrades the precision the seller declared and it moves the
privacy surface the seller vouched for. If declared resolution is the sole carrier
of both claims and conversion can silently change effective resolution, the
declaration is unverifiable on its own. Requested-versus-executed provenance is
the only place either claim can be checked against what actually ran.

One correction worth carrying into the narrative. Resolution is not itself a
privacy control. A resolution floor without a population or audience floor still
permits small-cell exposure in sparse geographies, where a coarse cell containing
three households is exactly as exposed as a fine cell in a dense city, because the
risk is driven by the count inside the cell rather than by the cell's area. A
population floor without a resolution floor still permits geometry drawn
specifically to isolate one household. Both constraints have to be stated
together, which is what the privacy_safe profile in section 9 encodes. A caveat
phrased purely in terms of resolution will read as sufficient and is not.

13. Conformance

Named modes without fixtures produce implementations that agree on vocabulary and
disagree on output. Conformance for this companion has two layers.

Fixtures pin exact numeric outputs with explicit per-field tolerances, and are
re-derived on every run by calling the implementation rather than stored as
answers. Coverage must include the pathological classes, not only the convenient
ones: an ordinary mid-latitude cell, a pentagon, an antimeridian-crossing cell, a
near-polar cell, a polygon with an interior ring, a polygon narrower than one cell
at the target resolution, and a polygon smaller than a single cell.

Property tests assert relationships that hold for every input:

  1. No densified boundary sample of a cell falls strictly inside its inscribed
    circle.
  2. Every densified boundary sample lies at or within the circumscribed radius.
  3. Every cell returned by full mode has its entire boundary inside the source
    polygon. A center check is not evidence for a full claim.
  4. uncompact(compact(cells), resolution) returns exactly the input set.
  5. For a cell partitioned by a set of regions with no gaps or overlaps, the
    coverage fractions across all cell-region links sum to 1 within tolerance. Below
    1 means a missed overlap, above 1 means double-counted area.

A conversion function with only normal-case fixtures has not been tested against
the inputs most likely to break it.

14. Custom systems

Support for custom_system_id as already proposed on #5969. A custom token
without unambiguous cross-party identification cannot interoperate, and a registry
path lets future open cell systems declare themselves without reopening the enum.

15. Open questions for the WG

  1. Does the conversion vocabulary belong in targeting.json, in a new
    cell-system.json, or in a non-normative implementation guide with only the
    declaration fields normative? This document assumes declaration fields are
    normative and the algorithms are guidance.
  2. Should sellers be required to declare their containment mode and circle mode in
    the capability response, or only to record them in reporting provenance?
    Declaring in capability lets a buyer choose a seller by conversion behavior
    before spending; recording in reporting only lets them audit afterwards.
  3. Is threshold containment worth naming, given it requires an additional
    declared parameter that the other three do not?
  4. Does the resolution declaration carry any coarseness guidance, or is fine
    resolution support a pure seller assertion? This is schema and therefore sits
    on the RFC: geo_cells / geo_cells_exclude targeting — hierarchical cell-grid systems as a declared geographic unit #5969 side, but it depends on the section 12 framing.

16. Note on drafting conventions

Text intended for the repository will need two adjustments before it is filed as
a PR. Normative schema fields cannot name platforms or vendors, so execution
primitives are described generically here as postal-code targeting,
point-and-radius targeting, and polygon targeting rather than by product name.
Examples must use fictional entities from the repository's registry.

17. Supporting material

The conversion algorithms, containment modes, circle derivations, quality metrics,
crosswalk mechanics, edge-case catalogue, and conformance fixture format
summarized here are documented in full elsewhere, with tested reference
implementations and machine-readable forms for both human and agent consumption.
The unit itself, including its temporal component, has its own walkthrough.

That material is offered as input to the WG rather than as a dependency. Nothing
in this companion requires adopting it, and every normative statement above stands
without it.

Metadata

Metadata

Assignees

No one assigned

    Labels

    claude-triagedIssue has been triaged by the Claude Code triage routine. Remove to re-triage.media-buyIssue concerns the media-buy protocol domainneeds-wg-reviewBlocked on a working-group decision — surface in WG meeting agendasrfcProtocol change — auto-adds to roadmap boardschemaJSON Schema source-of-truth: definitions, codegen artifacts, validation, hygienespec / protocol

    Type

    No type

    Projects

    Status
    No status

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions