Joining zoning attributes to tiles without rebuilding geometry

GEOMETRY_CLASSES = {"boundary_adjustment", "split", "merge"}
ATTRIBUTE_CLASSES = {"rezone", "overlay_only", "attribute_only"}


def change_mix(changes, days=365):
    """What fraction of a year's changes are attribute-only? That fraction is exactly
    the fraction of tile rebuilds the join eliminates."""
    from collections import Counter
    counts = Counter(c.change_class for c in changes)
    attr = sum(v for k, v in counts.items() if k in ATTRIBUTE_CLASSES)
    geom = sum(v for k, v in counts.items() if k in GEOMETRY_CLASSES)
    return {"attribute_only": attr, "geometry": geom,
            "attribute_share": round(attr / max(attr + geom, 1), 3),
            "by_class": dict(counts)}

import json
import hashlib


def build_state_file(parcels, taxonomy_version, as_of):
    """Compact by construction: parallel arrays rather than a list of objects, and
    class names replaced by indices into a legend. A county of 41 000 parcels lands
    around 40 kB gzipped, which is a 60-second-cacheable asset."""
    classes = sorted({p.canonical_class for p in parcels})
    class_index = {c: i for i, c in enumerate(classes)}

    ids, cls, ovl = [], [], []
    for p in sorted(parcels, key=lambda p: p.feature_id):
        ids.append(p.feature_id)
        cls.append(class_index[p.canonical_class])
        ovl.append(",".join(sorted(p.overlay_codes)))

    payload = {
        "as_of": as_of.isoformat(),
        "taxonomy_version": taxonomy_version,
        "legend": classes,
        "ids": ids,            # ascending, so a client can binary-search
        "class": cls,
        "overlays": ovl,
    }
    body = json.dumps(payload, separators=(",", ":")).encode()
    return body, hashlib.sha256(body).hexdigest()[:12]

// The join happens per rendered feature, so it must be O(1) per lookup.
async function loadZoningState(url) {
  const res = await fetch(url, { cache: 'no-cache' });   // short max-age on the server
  const s = await res.json();
  const byId = new Map();
  for (let i = 0; i < s.ids.length; i++) {
    byId.set(s.ids[i], { cls: s.class[i], overlays: s.overlays[i] });
  }
  return { ...s, byId };
}

function applyZoningState(map, state) {
  // setFeatureState is the mechanism that makes this cheap: it attaches data to
  // already-rendered features without re-parsing the tile.
  for (const [id, v] of state.byId) {
    map.setFeatureState({ source: 'parcels', sourceLayer: 'parcels', id },
                        { zoningClass: v.cls, overlays: v.overlays });
  }
}

// Styling reads feature state rather than a baked attribute.
const zoningPaint = {
  'fill-color': [
    'match', ['feature-state', 'zoningClass'],
    0, '#e0f2f1',   // indices into state.legend
    1, '#fde68a',
    2, '#d1fae5',
    /* … */
    '#cccccc',      // fallback: a class the style does not know
  ],
};

map.on('load', async () => {
  map.setPaintProperty('parcels-fill', 'fill-opacity', 0.15);   // muted, not invisible
  showStatus('Loading current zoning…');

  const state = await loadZoningState('/state/zoning.json');
  applyZoningState(map, state);

  map.setPaintProperty('parcels-fill', 'fill-opacity', 0.7);
  showStatus(`Zoning as of ${state.as_of}`);   // the map now says what it is showing

  // New tiles arrive as the user pans; their features need the state too.
  map.on('sourcedata', (e) => {
    if (e.sourceId === 'parcels' && e.isSourceLoaded) applyZoningState(map, state);
  });
});

def validate_pair(manifest, state_payload, tile_ids):
    """Refuse to publish a state file that does not match the pyramid it will be
    joined to. A mismatch renders parcels unstyled, which looks like a data outage."""
    state_ids = set(state_payload["ids"])
    problems = []

    missing = tile_ids - state_ids
    if missing:
        problems.append(f"{len(missing)} tile feature(s) have no state entry — they "
                        f"will render unstyled (e.g. {sorted(missing)[:3]})")

    orphaned = state_ids - tile_ids
    if orphaned:
        problems.append(f"{len(orphaned)} state entr(ies) reference features absent "
                        f"from the pyramid — a stale state file")

    if state_payload["taxonomy_version"] != manifest["taxonomy_version"]:
        problems.append(f"taxonomy mismatch: state {state_payload['taxonomy_version']} "
                        f"vs pyramid {manifest['taxonomy_version']}")

    if problems:
        raise StatePyramidMismatch("; ".join(problems))

def test_a_rezone_touches_only_the_state_file():
    before = pyramid_digest(TILES)
    apply_rezone(parcel_id="0714-22-1", new_class="MU-2")
    publish()
    assert pyramid_digest(TILES) == before          # the pyramid is untouched
    assert "MU-2" in read_state()["legend"]


def test_a_split_requires_a_pyramid_rebuild():
    before = pyramid_digest(TILES)
    apply_split(parcel_id="0714-22-1", into=["0714-22-1A", "0714-22-1B"])
    publish()
    assert pyramid_digest(TILES) != before          # geometry changed: rebuild required


def test_state_file_stays_small():
    body, _digest = build_state_file(COUNTY_PARCELS, "tax-v4", date.today())
    import gzip
    assert len(gzip.compress(body)) < 80_000        # a 60-second-cacheable asset


def test_publishing_a_mismatched_pair_is_refused():
    state, _ = build_state_file(PARCELS_AFTER_SPLIT, "tax-v4", date.today())
    with pytest.raises(StatePyramidMismatch, match="no state entry"):
        validate_pair(OLD_MANIFEST, json.loads(state), OLD_TILE_IDS)


def test_taxonomy_mismatch_is_refused():
    state, _ = build_state_file(COUNTY_PARCELS, "tax-v5", date.today())
    with pytest.raises(StatePyramidMismatch, match="taxonomy mismatch"):
        validate_pair(MANIFEST_V4, json.loads(state), TILE_IDS)