Project: publish a boundary-safe delivery-zone lake

Last updated: 6 Oct 20265 min read

project

Build a versioned location dataset whose grid layout stays efficient and whose zone assignments survive edge cases, corrections and shape revisions.

Construct the data and contract

Create 480 delivery events across three days, including a dense city cell, several sparse rural cells, a point on a zone border and two events with corrected coordinates. Define the coordinate order, supported range, event identity and border ownership rule. Keep a raw copy of rejected coordinates so they can be repaired without inventing a location. The source contract is the first validation boundary.

Choose and measure layout

Compare two grid resolutions with the same time partitions. Record populated cells, average and p95 files per cell, small-file count and bytes scanned for three user queries: one neighborhood, one cross-border radius and one full-city daily aggregate. Give the dense cell a bounded split while keeping sparse cells compact. A resolution that wins only the tiny neighborhood query may still be worse overall.

Build exact assignment

Generate conservative zone candidates from cell covers or bounding boxes, then run an exact geometry predicate. Plant a false-positive candidate inside a zone rectangle but outside its actual polygon and prove it is rejected. Test the point on the border according to the contract. If two zones overlap, either keep two rows with an explicit multi-membership grain or choose the deterministic priority winner.

Replay corrections and shape versions

Move one event across a cell and zone boundary, then publish a corrected generation. The old placement must disappear from the current view while remaining queryable through the retained snapshot. Change one polygon effective next day and prove that the earlier day keeps its old assignment. The atomic snapshot prevents readers from seeing only half the move.

Deliver a proof bundle

Provide the layouts, query costs, candidate-to-exact ratios, border fixtures, duplicate-ID check, old and new assignment sets, input and shape generations, and one failed publish attempt. Show that every accepted event appears in the correct output multiplicity. A map screenshot alone cannot prove no delivery vanished between adjacent cells.

Implementation

raw_deliveries = {"delivery-47": (4, 3), "delivery-48": (8, 8),
                  "delivery-49": (5, 4)}
old_cells = {delivery_id: (int(lon // 4), int(lat // 4))
             for delivery_id, (lon, lat) in raw_deliveries.items()}
corrected_deliveries = {**raw_deliveries, "delivery-49": (9, 4)}
new_cells = {delivery_id: (int(lon // 4), int(lat // 4))
             for delivery_id, (lon, lat) in corrected_deliveries.items()}

assert old_cells["delivery-49"] == (1, 1)
assert new_cells["delivery-49"] == (2, 1)
assert set(old_cells) == set(new_cells)  # move, not duplicate

Performance and operating cost

Assigning N points to coarse cells is O(N) time and O(N) output state. Exact spatial joining adds candidate generation, polygon checks and versioned output storage. Two resolution trials and retained snapshots increase temporary storage, but reveal whether reduced scan bytes outweigh extra metadata and correction work before the layout becomes a production dependency.

Common Mistakes

Do not use a cell-center-only polygon cover.
Do not leave the old cell assignment live after a coordinate correction.
Do not recompute historical zone totals with an unversioned current polygon.