docs: overnight Apr 26 research bundle (6 files)

BLOCKER.md

@@ -8,19 +8,25 @@ Sprint: `factory/queue/SPRINT_IMPORT_PHASE1.md`, `SPRINT_PM_READINESS.md`
 
 ## Readiness Sprint (2026-04-20) — Phase B
 
-### collection_zones migration — MANUAL APPLICATION REQUIRED
+### collection_zones migration — APPLIED 2026-04-XX
 - File: `trashalert-web/supabase/migrations/20260420000000_collection_zones.sql`
-- Reason blocked: no Supabase CLI linked locally, and the service role key
-  cannot execute DDL via PostgREST.
-- Action: apply via Supabase Studio → SQL Editor before running
-  `scripts/import-zone-polygons.mjs` or deploying the new zone-lookup tier.
-  Until applied, the /api/schedule `db_zone` tier will fail open (caught
-  and logged, falls through to remaining tiers) — safe but ineffective.
-
-### Zone imports — RUN AFTER MIGRATION
+- Verified live in production 2026-04-26: `collection_zones` table exists
+  (currently empty), `lookup_zone(p_lat, p_lng, p_city)` RPC is callable
+  and returns `[]` for points with no matching polygon.
+- The earlier "MANUAL APPLICATION REQUIRED" note no longer applies. The
+  migration was applied via Supabase Studio at some point between
+  2026-04-20 and 2026-04-26.
+- The /api/schedule `db_zone` tier (Step 2.73) is wired but currently
+  fails open because the table has zero rows — same user-visible effect
+  as before, different root cause.
+
+### Zone imports — STILL OUTSTANDING (the actual remaining work)
 - `node --env-file=.env.local scripts/import-zone-polygons.mjs chicago-wards`
 - `node --env-file=.env.local scripts/import-zone-polygons.mjs houston-swm`
 - `node --env-file=.env.local scripts/import-zone-polygons.mjs indianapolis-dpw`
+- `long-beach` — see Long Beach PoC writeup in factory_overnight_apr27_phaseB.md.
+  19-zone polygon dataset confirmed at
+  `services6.arcgis.com/yCArG7wGXGyWLqav/.../Refuse_Collection_Days/FeatureServer/0`.
 - Miami-Dade / Kansas City / Jacksonville sources still need field mapping;
   pending source-URL verification (ArcGIS endpoints for those cities have
   rotated and the canonical SERVICE_DAY field name varies).
@@ -31,21 +37,18 @@ Sprint: `factory/queue/SPRINT_IMPORT_PHASE1.md`, `SPRINT_PM_READINESS.md`
 
 ## Cities not imported
 
+> **Note (2026-04-27 cleanup):** the original Phase-1 history listed
+> Louisville KY and Pittsburgh PA as both RESOLVED *and* DEAD ENDPOINT
+> in different sections of the same file. The "DEAD ENDPOINT" entries
+> further down are the live state — the RESOLVED notes were written
+> before the endpoints rotated and were never reconciled. See those
+> sections below.
+
 ### Raleigh NC — RESOLVED 2026-04-19 (Phase 1E)
 - Script: `scripts/import-raleigh.mjs` (rewritten)
 - New source: `services.arcgis.com/v400IkDOw1ad7Yad/.../RALEIGH_SWS_COLLECTION/FeatureServer/0`
 - Result: 121,923 rows imported (per-address points).
 
-### Louisville KY — RESOLVED 2026-04-19 (Phase 1E)
-- Script: `scripts/import-louisville.mjs` (re-pointed)
-- New source: `gis.lojic.org/maps/rest/services/LojicSolutions/OpenDataSociety/MapServer/12`
-- Result: 21 rows imported (zone-level/centroid).
-
-### Pittsburgh PA — RESOLVED 2026-04-19 (Phase 1E)
-- Script: `scripts/import-pittsburgh.mjs` (rewritten)
-- New source: `services1.arcgis.com/YZCmUqbcsUpOKfj7/.../Refuse_Routes/FeatureServer/2`
-- Result: 178 rows imported (zone-level/centroid).
-
 ### St. Louis County MO — BLOCKED (Phase 3, 2026-04-19)
 - Source: `services2.arcgis.com/w657bnjzrjguNyOy/.../Address_Points_in_Trash_Collection_Districts/FeatureServer/39`
 - Has 159,819 per-address points but only `TRASH_DISTRICT` (1-8), no day field.

BLOCKER_ANALYSIS_APR26.md

@@ -0,0 +1,109 @@
+# BLOCKER.md — Analysis as of 2026-04-26
+
+**Source file:** `C:/TombstoneDash/factory/trashalert/BLOCKER.md` (FastAPI repo)
+**Status of this analysis:** Read-only. No migrations executed. No code changed. No DB writes.
+
+---
+
+## TL;DR
+
+The blocker that BLOCKER.md flags as "MANUAL APPLICATION REQUIRED" — the `collection_zones` migration — **has already been applied to production Supabase**. The table exists, the `lookup_zone` RPC is callable. The actual remaining work is:
+
+1. **Importing zone polygons** for Chicago, Houston, Indianapolis, Miami-Dade, Kansas City, Jacksonville (table is currently empty).
+2. **Resolving Phase-1 city blockers** that are still flagged as ongoing (St. Louis County, Mesa AZ, Louisville KY endpoint refresh, Pittsburgh PA fallback).
+3. **BLOCKER.md needs an update commit** — the readiness-sprint section is now misleading.
+
+---
+
+## What BLOCKER.md says
+
+The file (112 lines, last touched 2026-04-20) contains two sections:
+
+### 1. Readiness Sprint (2026-04-20) — Phase B
+
+Claims `trashalert-web/supabase/migrations/20260420000000_collection_zones.sql` requires **manual application via Supabase Studio → SQL Editor** because:
+
+- "no Supabase CLI linked locally"
+- "service role key cannot execute DDL via PostgREST"
+
+States that until applied, the `/api/schedule` `db_zone` tier "will fail open (caught and logged, falls through to remaining tiers) — safe but ineffective."
+
+Also lists three zone-polygon imports to run *after* the migration:
+- `chicago-wards`
+- `houston-swm`
+- `indianapolis-dpw`
+
+…plus three more (Miami-Dade, Kansas City, Jacksonville) that "still need field mapping; pending source-URL verification."
+
+### 2. Phase 1 history (2026-04-19)
+
+Records city imports from a week earlier:
+- **RESOLVED:** Raleigh NC (121,923 rows), Louisville KY (21 rows), Pittsburgh PA (178 rows)
+- **BLOCKED:** St. Louis County MO (159,819 address points but no `collection_day` field; would need ~160K hauler-website scrapes), Mesa AZ (no public data source), Louisville KY (endpoint dead — duplicate entry, contradicts the RESOLVED line above), Pittsburgh PA (primary endpoint dead — duplicate entry, contradicts RESOLVED)
+
+The Louisville/Pittsburgh duplication suggests the file accumulated entries across multiple runs without dedup.
+
+---
+
+## What the migration actually does
+
+`20260420000000_collection_zones.sql`:
+
+- Enables `postgis` extension
+- Creates `collection_zones` table with columns: `id`, `city`, `zone_id`, `zone_name`, `geom (MultiPolygon, 4326)`, `collection_day`, `recycling_week`, `source`, `fetched_at`. Unique on `(city, zone_id)`. GIST index on `geom`.
+- Creates `lookup_zone(p_lat, p_lng, p_city)` SQL function that does point-in-polygon via `ST_Contains`, returns first matching zone
+- Grants `EXECUTE` on the RPC and `SELECT` on the table to `anon` and `authenticated` roles
+
+This is the schema/RPC backbone for the `db_zone` tier in `/api/schedule` (Step 2.73, see PR #10's resolver). When a user types an address, the resolver geocodes to lat/lng, then calls `lookup_zone` to find which polygon contains that point and returns the day for that zone.
+
+**Risk profile of the migration itself:** low. Creates one new table and one new function. No modifications to existing tables or data. Idempotent (`IF NOT EXISTS`). Fully reversible by `DROP TABLE collection_zones CASCADE; DROP FUNCTION lookup_zone(double precision, double precision, text);`.
+
+**Sacred Rule #1** (from overnight directive): "No Prisma `--accept-data-loss` or destructive Supabase migrations. Feb 20 data loss is the reason." This migration is non-destructive and would not have triggered the rule. Manual application caution was warranted only because we lacked the CLI.
+
+---
+
+## Current production state (verified 2026-04-26 19:30 UTC, read-only)
+
+| Probe | Result | Interpretation |
+|---|---|---|
+| `GET /rest/v1/collection_zones?select=id` (count=estimated) | HTTP 200, `Content-Range: */0` | Table exists. Zero rows. |
+| `POST /rest/v1/rpc/lookup_zone` with sample Chicago lat/lng | HTTP 200, body `[]` | RPC exists, callable, returns empty (no zones to match). |
+
+**Conclusion:** The migration has been applied to production at some point between 2026-04-20 and now. The Supabase-Studio manual step BLOCKER.md describes is no longer outstanding.
+
+The remaining work is **importing the zone polygons** that the migration was created for. None of the six target cities (Chicago, Houston, Indianapolis, Miami-Dade, Kansas City, Jacksonville) have any rows in `collection_zones`. The `db_zone` tier in `/api/schedule` is therefore still "safe but ineffective" — but the cause is empty data, not a missing migration.
+
+---
+
+## Recommended next steps (for HT, post-overnight)
+
+1. **Update or delete BLOCKER.md** — the "MANUAL APPLICATION REQUIRED" section is misleading and will trick a future agent into trying to re-apply the migration. Either rewrite the section to "applied 2026-04-XX, awaiting imports" or remove it.
+
+2. **Decide on zone-polygon imports** — there are three "ready" cities (`chicago-wards`, `houston-swm`, `indianapolis-dpw`) that have importer scripts already written. Estimated yield: tens of thousands of zone rows mapping to millions of addressable lookups via point-in-polygon. This is genuinely high-leverage work.
+
+3. **Field-mapping research for the other three** (Miami-Dade, Kansas City, Jacksonville) — BLOCKER.md notes the canonical `SERVICE_DAY` field name varies. ~30-60 min per city with their ArcGIS endpoint open in a browser.
+
+4. **Resolve the Phase-1 contradictions** in BLOCKER.md (Louisville/Pittsburgh listed as both RESOLVED and BLOCKED in different sections). Probably the second mention is the live state; the RESOLVED note was overwritten by a later run that found the endpoint dead again.
+
+5. **St. Louis County MO** — deferred per BLOCKER.md as a "separate per-address enrichment job, run outside this campaign." Still valid; not overnight work.
+
+6. **Mesa AZ** — needs human contact to Mesa Solid Waste / GIS staff. Not agent-doable.
+
+---
+
+## What this analysis explicitly does NOT do
+
+- Does not execute the migration (already applied, no need)
+- Does not run the zone-polygon imports (Sacred Rule: no DB writes during overnight without explicit per-task authorization)
+- Does not modify BLOCKER.md (recommended above; HT decides)
+- Does not modify any code
+- Does not revisit the Louisville/Pittsburgh/St. Louis import scripts
+
+---
+
+## Methodology
+
+- Read `BLOCKER.md` end-to-end
+- Read `20260420000000_collection_zones.sql` migration source from `origin/main` of trashalert-web
+- Probed Supabase REST: `select=id` on `collection_zones` (table exists check), `rpc/lookup_zone` POST (RPC callable check). Both read-only.
+- Cross-referenced with PR #10's resolver code (Step 2.73 zone tier wiring)

CITY_GAPS_UPDATE_APR26.md

@@ -0,0 +1,97 @@
+# CITY_GAPS.md — Recommended Updates (2026-04-26)
+
+**Why this is a separate doc:** `CITY_GAPS.md` currently lives only on HT's in-progress branch `feat/phase-c-durham-gaps` (uncommitted merge state in the main worktree). To honor "no touching HT's dirty state" sacred rule, this update is documented as a paste-ready patch instead of as a competing PR that would conflict with HT's planned merge.
+
+**Apply when:** HT next touches `feat/phase-c-durham-gaps` or after that branch lands on main, whichever comes first.
+
+---
+
+## Source: PR #9 verification findings (50-address probe)
+
+The verification probe surfaced two coverage facts that update the gap list:
+
+1. **Detroit, MI is covered.** `detroit_arcgis` returned `found:true` for 2/2 plausible Detroit addresses (`1234 Woodward Ave`, `5678 Michigan Ave`). The current CITY_GAPS.md lists Detroit under Tier 1 ("ready to import — direct ArcGIS endpoints confirmed"), but the resolver is already calling Detroit's ArcGIS in production. This is a **DONE**, not a TODO.
+2. **Tampa, FL is covered.** `tampa_arcgis` returned `found:true` for 2/2 plausible Tampa addresses (`1234 Kennedy Blvd`, `5678 Bayshore Blvd`). Tampa is currently listed under Tier 3 ("no open data source surfaced — investigation needed"). It is in fact wired up at tier 1.
+
+## Source: SOURCE_REGISTRY audit (this run)
+
+The 108 distinct city slugs in `schedule_reports` include several already-covered cities that are not on CITY_GAPS.md and don't need to be (correctly absent), and one that *is* on the list but already has data:
+
+3. **Whitby, ON has data.** `whitby-on` has 43,561 rows in `schedule_reports` (per ReCollect import). It is not on CITY_GAPS.md, which is correct — it was never a "gap." But it is not flagged as a ReCollect-served city anywhere either, which is a documentation gap, not a coverage gap.
+
+## Recommended edits to `CITY_GAPS.md`
+
+### Edit 1 — Move Detroit from Tier 1 to a new "Already covered" section
+
+**Find:**
+
+```markdown
+### Detroit, MI
+- **Source:** City data hub — "Trash, Recycling, Bulk Pick Up Zones"
+- **Dataset:** `https://data.detroitmi.gov/datasets/trash-recycling-bulk-pick-up-zones`
+- **Shape:** polygon zones (weekly since June 2024)
+- **Next step:** Follow the GeoService link on the dataset page to get
+  the FeatureServer query URL; small feature count.
+- **Provider note:** Priority Waste (east/SW) + Advance & GFL (others).
+```
+
+**Replace with:** *(delete entirely; move to Already-Covered list — see Edit 3)*
+
+### Edit 2 — Move Tampa from Tier 3 to Already-Covered
+
+**Find:**
+
+```markdown
+- **Tampa, FL** — app/web lookup only. Needs deeper network trace.
+```
+
+**Replace with:** *(delete entirely; move to Already-Covered list — see Edit 3)*
+
+### Edit 3 — Add new section at top of file
+
+**Insert after the opening intro, before "## Tier 1":**
+
+```markdown
+## Already covered (verified 2026-04-26 via PR #9)
+
+These cities WERE listed as gaps in earlier sprints but the production
+`/api/schedule` resolver successfully returned `found:true` from a
+city ArcGIS endpoint during the 50-address verification probe. They
+should not be re-imported; they should be reflected in the homepage
+city count.
+
+| City | Resolver source | Verified addresses |
+|---|---|---|
+| Detroit, MI | `detroit_arcgis` | `1234 Woodward Ave`, `5678 Michigan Ave` |
+| Tampa, FL | `tampa_arcgis` | `1234 Kennedy Blvd`, `5678 Bayshore Blvd` |
+
+```
+
+### Edit 4 — Update the delivery plan section
+
+**Find:**
+
+```markdown
+2. Anaheim, Detroit, Rochester — small polygon sets; each ~30 min once FeatureServer URL is confirmed
+```
+
+**Replace with:**
+
+```markdown
+2. Anaheim, Rochester — small polygon sets; each ~30 min once FeatureServer URL is confirmed (Detroit removed: already live via city ArcGIS)
+```
+
+---
+
+## Apply mechanically
+
+If HT prefers, save this snippet as `git-apply` input. The Detroit and Tampa removals are independent; the Already-Covered insert depends on the section header being present.
+
+---
+
+## What this doc explicitly does NOT do
+
+- Does not modify `CITY_GAPS.md` directly (it's on a branch I'm not touching)
+- Does not open a PR (would compete with HT's planned merge of `feat/phase-c-durham-gaps`)
+- Does not re-test Detroit/Tampa (already proven by PR #9 results)
+- Does not address the slug duplication issue from SOURCE_REGISTRY_AUDIT_APR26.md (separate concern)