GIS Boundary Explorer, Study Design Refactors, and Deployment Hardening

A busy Tuesday on Parthenon with work spanning three distinct fronts: consolidating the GIS layer we stood up in Phase 19, continuing to clean up the study design workbench on the frontend, and tightening several infrastructure and testing rough edges that had accumulated over the sprint.

GIS Layer Consolidation — PostGIS, Boundary Explorer, and OHDSI Roadmap

The big structural commit today (7acd3b0ab) wraps up the loose ends left after Phase 19's five-wave rollout of urban/rural stratification. That phase got data into the gis schema — 3,234 counties, 14,401 HUD ZIP↔county crosswalk rows, 416K patient geography records — but a handful of integration issues needed to be resolved before the layer could be considered stable.

PostGIS search_path fix: Spatial queries were silently falling back to the public schema in certain session contexts because PostGIS extension functions aren't schema-qualified inside the extension itself. The fix pins search_path correctly so that gis.* functions resolve against the PostGIS-enabled schema without ambiguity. This is a subtle but load-bearing fix — without it, geometry operators would fail unpredictably depending on how a connection was established.

Boundary Explorer: A new UI surface for browsing geographic boundaries has been wired in. Researchers can now visually inspect which counties belong to which urban/rural classification tier before committing to a stratification design — useful for sanity-checking cohort geography before running a full incidence-rate analysis.

OHDSI TODO file: A planning artifact was committed alongside the GIS work cataloguing the remaining alignment work needed to bring the gis schema into full conformance with OMOP Location conventions. This is intentionally tracked in the repo rather than an external ticket system so future contributors have context immediately when touching this area.

Study Design Workbench Refactors

Two meaningful frontend refactors landed today under the studies domain, both aimed at making the workbench code more maintainable as complexity grows.

useStudyDesignWorkbench() hook extraction (1813d32a9): Logic that was previously scattered across the study design page component has been lifted into a dedicated custom hook. The hook encapsulates workbench state, dirty-tracking, and the coordination between the local draft and the persisted design. This makes the page component substantially thinner and sets up a clean seam for testing workbench behavior in isolation without rendering overhead. The commit is tagged 260428-gu8 for traceability back to the planning artifact.

Zod schema parsing in intent assistance (21b8aa2ed): The pattern of drilling valueAt accessors deep into nested form state to feed the intent assistance system has been replaced with explicit Zod schema parsing at the boundary. This matters because valueAt chains are brittle — a schema change silently produces undefined rather than a parse error, and bugs in the assistance suggestions are hard to trace back to their source. Zod's .safeParse() gives us structured error output and forces the shape of intent assistance inputs to be explicitly declared.

if_unmodified_since lock mutation (238cf46c5): The optimistic concurrency guard for study designs — which prevents two researchers from overwriting each other's changes — now correctly threads the If-Unmodified-Since header through the frontend mutation call. Previously the header was being generated server-side but not respected end-to-end from the client, meaning the lock was advisory at best.

Testing Infrastructure Improvements

Several commits addressed test reliability and environment hygiene.

PHPUnit DB env var overrides (0364cb637): Database connection environment variables used by PHPUnit are now settable as defaults that can be overridden at the shell level. Previously the test suite would only honor values baked into .env.testing, making it cumbersome to point tests at an alternate database without editing tracked files. This is particularly useful in CI matrix jobs.

Protected-DB guard exemption for php artisan test (2b32c5c5f): The safety guard that prevents accidental writes to production-tagged databases was incorrectly firing when running php artisan test locally, because the Artisan test runner shares a process with the application bootstrap. The guard now explicitly exempts the test command path so developers aren't blocked by false positives during the inner loop.

FinnGen schema teardown fix (08913f265): The FinnGen integration test suite was dropping its test schema in afterAll rather than afterEach, meaning a failing test mid-suite would leave schema debris that poisoned subsequent runs. Moving teardown to afterEach makes each test case independently clean.

Deployment and Broadcast Hardening

Compose service list caching (9f949d5f8): The smoke-test step in the deployment pipeline queries the Docker Compose service list to verify all expected containers are healthy. Under load, this query was occasionally returning a partial list due to a race with the Compose engine, triggering false-positive warnings in Slack. The fix caches the service list at the start of the smoke-test job rather than re-querying it dynamically, eliminating the transient failures.

hasSession() guard in broadcast (e7277c448): The broadcast layer was calling session()->getId() unconditionally in a context where sessions aren't always initialized — specifically in queue worker processes that handle broadcast events. Wrapping the call with hasSession() prevents the cryptic "Session store not set on request" exception that was appearing sporadically in worker logs.

What's Next

With the GIS layer consolidated and the PostGIS path fixed, the immediate next step is completing the OHDSI Location conformance work catalogued in today's TODO artifact — specifically aligning gis.geographic_location PKs with OMOP location_id so that standard OHDSI tools can traverse the geography tables without a translation layer.

On the study design side, the useStudyDesignWorkbench() hook extraction opens the door to adding workbench-level unit tests, which are currently absent. Expect those to start landing in the next few sessions alongside continued cleanup of the intent assistance pipeline now that the Zod parsing boundary is established.