Representing planned unit developments as parcel-specific overlays

def audit_pud_candidates(parcels, registry):
    """Codes that look like a per-development approval rather than a district."""
    import re
    suspicious = []
    for code, n in parcels["base_code"].value_counts().items():
        if not re.match(r"^(PUD|PD|SPA|MPD)[-\s]?\d+", code.upper()):
            continue
        suspicious.append({
            "code": code,
            "parcels": n,
            "in_district_registry": code in registry.districts,
            # A district serves many unrelated areas; a PUD serves one contiguous
            # development. Contiguity is the giveaway.
            "contiguous": is_one_contiguous_group(parcels, code),
        })
    return suspicious

-- The class: there is exactly one row for PUDs, describing how a PUD composes.
INSERT INTO overlay_registry (code, kind, precedence, ordinance_ref, notes) VALUES
  ('PUD', 'replace', 0,  'title 14 ch. 9',
   'A PUD replaces named standards and leaves the rest to the underlying district. '
   'Precedence 0: a site-specific approval outranks area-wide overlays.');

-- The instances: one row per approved development, with its own standards.
CREATE TABLE overlay_instance (
    instance_id     text PRIMARY KEY,          -- 'PUD-2024-118'
    overlay_code    text NOT NULL REFERENCES overlay_registry(code),
    jurisdiction    text NOT NULL,
    ordinance_ref   text NOT NULL,             -- 'Ord. 2024-118'
    adopted_on      date NOT NULL,
    expires_on      date,                      -- PUDs can lapse if unbuilt
    numeric         jsonb NOT NULL DEFAULT '{}',
    uses_added      text[] NOT NULL DEFAULT '{}',
    uses_removed    text[] NOT NULL DEFAULT '{}',
    requirements    text[] NOT NULL DEFAULT '{}',
    CONSTRAINT expires_after_adoption CHECK (expires_on IS NULL OR expires_on > adopted_on)
);

-- Membership is per parcel, because a PUD's boundary is the approval's boundary and
-- follows nothing else.
CREATE TABLE overlay_instance_member (
    instance_id text NOT NULL REFERENCES overlay_instance(instance_id),
    parcel_id   text NOT NULL,
    -- Some standards apply only to part of a PUD — a setback along one internal
    -- street. A sub-area label carries that without a second instance.
    sub_area    text,
    PRIMARY KEY (instance_id, parcel_id)
);

def overlays_for(parcel_id, as_of, registry, instances) -> list[Overlay]:
    """Area-wide overlays come from geometry; instance overlays come from membership,
    and each carries ITS OWN standards."""
    out = [registry.overlay(code) for code in registry.area_overlays_for(parcel_id, as_of)]

    for inst in instances.for_parcel(parcel_id, as_of):
        cls = registry.overlay(inst.overlay_code)
        out.append(Overlay(
            code=inst.instance_id,               # 'PUD-2024-118', not 'PUD'
            kind=cls.kind,
            precedence=cls.precedence,
            ordinance_ref=inst.ordinance_ref,    # the approving ordinance, not the chapter
            numeric=inst.numeric_for(parcel_id), # honours sub_area
            uses_added=frozenset(inst.uses_added),
            uses_removed=frozenset(inst.uses_removed),
            requirements=tuple(inst.requirements),
        ))
    return out

def active_instances(instances, parcel_id, as_of):
    """A PUD approval can lapse. An expired instance must stop applying on its
    expiry date, at which point the underlying district governs again — which is a
    change event nobody publishes, because no data changed."""
    return [i for i in instances.for_parcel(parcel_id, as_of)
            if i.adopted_on <= as_of and (i.expires_on is None or as_of < i.expires_on)]

def test_pud_standards_do_not_leak_between_instances(registry, instances):
    a = resolve(BASE_R1, overlays_for("p-in-118", DATE, registry, instances))
    b = resolve(BASE_R1, overlays_for("p-in-042", DATE, registry, instances))
    assert a.numeric["height_ft"] == 45.0      # Ord. 2024-118
    assert b.numeric["height_ft"] == 38.0      # Ord. 2019-042
    assert a.cite("height_ft") != b.cite("height_ft")


def test_unspecified_standards_fall_back_to_the_district(registry, instances):
    r = resolve(BASE_R1, overlays_for("p-in-118", DATE, registry, instances))
    assert r.numeric["rear_setback_ft"] == 20.0        # the PUD is silent on this
    assert r.cite("rear_setback_ft") == "base:R-1"     # so the district still governs


def test_sub_area_setback_applies_only_where_declared(registry, instances):
    inner = resolve(BASE_R1, overlays_for("p-118-inner-street", DATE, registry, instances))
    outer = resolve(BASE_R1, overlays_for("p-118-perimeter", DATE, registry, instances))
    assert inner.numeric["front_setback_ft"] == 12.0
    assert outer.numeric["front_setback_ft"] == 25.0   # district value


def test_expired_pud_stops_applying(registry, instances):
    before = resolve(BASE_R1, overlays_for("p-in-lapsed", date(2026, 1, 1), registry, instances))
    after = resolve(BASE_R1, overlays_for("p-in-lapsed", date(2027, 1, 1), registry, instances))
    assert before.numeric["height_ft"] == 45.0
    assert after.numeric["height_ft"] == 35.0          # back to the district
    assert after.cite("height_ft") == "base:R-1"


def test_district_registry_has_no_pud_instances(registry):
    """The structural assertion: instances must not pollute the district list."""
    assert not [d for d in registry.districts if d.upper().startswith(("PUD", "PD-"))]