Development -> Main, Sync

.env.example

@@ -1,4 +1,6 @@
 # Frontend
-# URL of the sawgraph-api service (e.g. http://localhost:3001 in dev,
-# https://sawgraph-api.onrender.com in prod).
+# URL of the API service:
+#   local dev   http://localhost:3001
+#   development https://sawgraph-explorer-api-development.up.railway.app
+#   production  https://sawgraph-explorer-api.up.railway.app
 VITE_API_BASE_URL=http://localhost:3001

.github/workflows/checks.yml

@@ -0,0 +1,72 @@
+name: Checks
+
+# The repo's self-checks, on every pull request. They were all runnable before
+# this file existed and none of them ran unless someone remembered to, which is
+# how an engine bug that every one of these styles of check would have caught
+# (upstream tracing the relation backwards, see docs/DEBUGGING.md 2026-09-16)
+# survived from the first commit to 2026-09-16.
+#
+# Everything here is offline and takes seconds. No secrets, no SPARQL, no
+# endpoint concurrency group: the live-endpoint workflows (health-check.yml,
+# warm-cache.yml) are the ones that have to queue.
+
+on:
+  pull_request:
+  push:
+    branches: [main, development]
+  workflow_dispatch:
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+
+      # react-leaflet's peer range does not include React 19 (see CLAUDE.md)
+      - run: npm ci --legacy-peer-deps
+
+      - name: Build (tsc -b && vite build)
+        run: npm run build
+
+      # Each of these asserts something that is silent when wrong: a wrong
+      # answer, a mislabelled step, a cache key that collides. They fail the
+      # build rather than reporting, because a self-check nobody is obliged to
+      # read is a self-check that does not exist.
+      - name: Trace direction
+        run: npm run check-trace-direction
+
+      - name: Flowline scope
+        run: npm run check-flowline-scope
+
+      - name: Cache key
+        run: npm run check-cache-key
+
+      - name: Step labels
+        run: npm run check-step-labels
+
+      - name: Substance labels
+        run: npm run check-substance-labels
+
+      - name: Query join order and observation joins
+        run: npm run check-query-joins
+
+      # Golden-file diff of the SPARQL every shape generates. The one above
+      # asserts a rule; this one notices when a change moves a shape nobody was
+      # thinking about, which is the failure mode of a shared query builder.
+      - name: Query snapshots
+        run: npm run check-query-snapshots
+
+      # Not blocking yet: `npm run lint` reports 15 pre-existing errors, all in
+      # components and none related to the engine. Make this a required step in
+      # the same change that clears them, not before, or the signal is noise
+      # from day one.
+      - name: Lint (advisory)
+        run: npm run lint
+        continue-on-error: true

.github/workflows/health-check.yml

@@ -0,0 +1,135 @@
+name: Dashboard health
+
+# Runs every dashboard question against the live endpoints once a week and
+# writes down what happened: worked or not, how long, how many rows. The point
+# is dating a regression. Without this, "the Indiana question broke sometime in
+# the last month" is the best anyone can say.
+#
+# Both branches are measured because they hit the same SPARQL endpoints — so a
+# difference between main and development is a difference in *our* code.
+#
+# No secrets. This never reads or writes the result cache: a cached answer would
+# report on the cache rather than on the graph.
+#
+# The schedule only fires once this file is on the default branch (main) —
+# GitHub ignores cron in workflows that live only on a feature branch.
+
+on:
+  schedule:
+    - cron: '0 6 * * 1' # Mondays, 06:00 UTC
+  workflow_dispatch:
+
+# One job at a time across *every* workflow that queries the graph — this group
+# name is shared with warm-cache.yml on purpose. Both run the same eight heavy
+# questions, and a warm run started by hand on a Monday morning would otherwise
+# land on top of the health cron. That is not hypothetical: three questions were
+# recorded as broken while this was being built, purely because something else
+# was querying at the same time, and all three passed on retry.
+concurrency:
+  group: sawgraph-endpoint
+  cancel-in-progress: false
+
+permissions:
+  contents: write # commit the history file and status page
+  issues: write # open an issue when a question regresses
+
+jobs:
+  measure:
+    runs-on: ubuntu-latest
+    timeout-minutes: 90
+
+    steps:
+      - name: Check out development (the branch results are committed to)
+        uses: actions/checkout@v4
+        with:
+          ref: development
+
+      - name: Check out main alongside it
+        uses: actions/checkout@v4
+        with:
+          ref: main
+          path: main-ref
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+
+      # react-leaflet's peer range does not include React 19 (see CLAUDE.md)
+      - run: npm ci --legacy-peer-deps
+
+      - name: Measure development
+        id: dev
+        # bash, not the default sh-with-e: without pipefail the exit code would
+        # be tee's, and a regression would sail through as a pass.
+        shell: bash
+        run: npm run health-check -- development | tee dev.log
+        continue-on-error: true
+
+      - name: Install main's dependencies
+        working-directory: main-ref
+        run: npm ci --legacy-peer-deps
+
+      # Runs main's code, but appends to development's history file so both
+      # branches land in one commit and one status page.
+      - name: Measure main
+        id: main
+        working-directory: main-ref
+        shell: bash
+        run: npm run health-check -- main --out "$GITHUB_WORKSPACE/docs/health/history.jsonl" | tee "$GITHUB_WORKSPACE/main.log"
+        continue-on-error: true
+
+      - name: Commit the results
+        run: |
+          git config user.name 'github-actions[bot]'
+          git config user.email 'github-actions[bot]@users.noreply.github.com'
+          git add docs/health/
+          if git diff --cached --quiet; then
+            echo "Nothing changed."
+          else
+            git commit -m "chore: dashboard health $(date -u +%Y-%m-%d)"
+            git push
+          fi
+
+      - name: Summary
+        if: always()
+        run: |
+          {
+            echo "### Dashboard health"
+            echo
+            echo '```'
+            tail -24 dev.log 2>/dev/null || echo "development: no output"
+            echo
+            tail -24 main.log 2>/dev/null || echo "main: no output"
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      # Exit code 2 from the script means a question that worked last week does
+      # not work now. An issue rather than just a red X, because a red X in a
+      # weekly job is easy to miss for another week.
+      - name: Open an issue for regressions
+        if: steps.dev.outcome == 'failure' || steps.main.outcome == 'failure'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          {
+            echo "The weekly health check found a dashboard question that worked before and does not now."
+            echo
+            echo "See [the run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) and [docs/health/STATUS.md](${{ github.server_url }}/${{ github.repository }}/blob/development/docs/health/STATUS.md)."
+            echo
+            for log in dev.log main.log; do
+              [ -f "$log" ] || continue
+              echo "### ${log%.log}"
+              echo '```'
+              sed -n '/REGRESSIONS/,$p' "$log" 2>/dev/null | head -40
+              echo '```'
+            done
+          } > issue.md
+          gh issue create \
+            --title "Dashboard health: a question regressed ($(date -u +%Y-%m-%d))" \
+            --body-file issue.md \
+            --label bug
+
+      - name: Fail if a question regressed
+        if: steps.dev.outcome == 'failure' || steps.main.outcome == 'failure'
+        run: exit 1

.github/workflows/warm-cache.yml

@@ -0,0 +1,85 @@
+name: Warm result cache
+
+# Runs the dashboard questions and stores their results, so visitors get them
+# instantly instead of waiting 10-70s for a live pipeline run.
+#
+# Manual on purpose: a cached entry only goes stale when the knowledge graph
+# reloads or its 30-day TTL expires, and both are things we control. To make it
+# periodic anyway, add a schedule trigger:
+#
+#   schedule:
+#     - cron: '0 6 * * 1'   # Mondays, 06:00 UTC
+#
+# Setup (once): add the repository secrets CACHE_WRITE_TOKEN_DEV and
+# CACHE_WRITE_TOKEN_PROD, matching CACHE_WRITE_TOKEN on each API service.
+
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: Which API to warm
+        type: choice
+        required: true
+        default: development
+        options: [development, production]
+      only:
+        description: 'Optional: only questions whose title contains this text'
+        type: string
+        required: false
+      allow_partial:
+        description: Cache results even when some slices failed
+        type: boolean
+        default: false
+
+# One job at a time across *every* workflow that queries the graph — shared with
+# health-check.yml, so a warm run and the weekly health check queue rather than
+# compete for the same graph engine. Warming both environments now serialises
+# too, which costs a few minutes and buys clean measurements.
+concurrency:
+  group: sawgraph-endpoint
+  cancel-in-progress: false
+
+jobs:
+  warm:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+
+      # react-leaflet's peer range does not include React 19 (see CLAUDE.md)
+      - run: npm ci --legacy-peer-deps
+
+      - name: Warm the cache
+        env:
+          API_BASE: >-
+            ${{ inputs.environment == 'production'
+                && 'https://sawgraph-explorer-api.up.railway.app'
+                || 'https://sawgraph-explorer-api-development.up.railway.app' }}
+          CACHE_WRITE_TOKEN: >-
+            ${{ inputs.environment == 'production'
+                && secrets.CACHE_WRITE_TOKEN_PROD
+                || secrets.CACHE_WRITE_TOKEN_DEV }}
+          ALLOW_PARTIAL: ${{ inputs.allow_partial && '1' || '0' }}
+        run: |
+          if [ -z "$CACHE_WRITE_TOKEN" ]; then
+            echo "::error::No cache write token for '${{ inputs.environment }}'."
+            echo "::error::Add CACHE_WRITE_TOKEN_DEV / CACHE_WRITE_TOKEN_PROD as repository secrets."
+            exit 1
+          fi
+          npm run warm-cache -- "${{ inputs.only }}" | tee warm-cache.log
+
+      - name: Summary
+        if: always()
+        run: |
+          {
+            echo "### Warm result cache — ${{ inputs.environment }}"
+            echo
+            echo '```'
+            tail -20 warm-cache.log 2>/dev/null || echo "no output"
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"

README.md

@@ -38,8 +38,19 @@ npm run preview  # Preview production build
 
 ## Deployment
 
-Deployed on **Railway** from the `main` branch. Build config lives in the Railway
-dashboard, not in this repo — there is no `railway.json` or `nixpacks.toml` here.
+Deployed on **Railway**, two environments, each with a frontend and an API
+service. Build config lives in the Railway dashboard, not in this repo — there
+is no `railway.json` or `nixpacks.toml` here.
+
+| Environment | Branch | Frontend | API |
+| --- | --- | --- | --- |
+| Production | `main` | https://sawgraph-explorer.up.railway.app | https://sawgraph-explorer-api.up.railway.app |
+| Development | `development` | https://sawgraph-explorer-development.up.railway.app | https://sawgraph-explorer-api-development.up.railway.app |
+
+The frontend reaches the API through `VITE_API_BASE_URL`, baked in at build
+time, so each environment's frontend points at its own API. The API allows the
+frontend's origin via `FRONTEND_ORIGIN`. Both services share a Postgres
+instance per environment.
 
 ## How queries work
 
@@ -56,9 +67,14 @@ When you click Apply, the query engine:
 2. **Executes** steps sequentially (`engine/executor.ts`), threading S2 cell sets between steps
 3. **Renders** results as map layers (`resultTransformer.ts` → `MapFeature[]`)
 
-Supported entity types: **samples**, **facilities**, **water bodies**
+Supported entity types: **samples**, **facilities**, **water bodies**, **wells**, **streams**
 Supported relationships: **near** (~1–2 km), **downstream**, **upstream**
 
+Downstream/upstream traces accept an optional cumulative flowpath cutoff
+(`Within N km of flow`). Unset, the trace is the full transitive closure.
+`node scripts/flow-distance-check.mjs` verifies the bounded trace against the
+live endpoints.
+
 ## SPARQL endpoints
 
 All hosted at `apps.okn.us`:
@@ -85,11 +101,16 @@ All hosted at `apps.okn.us`:
 
 Inside `docs/`:
 
-| File              | Contents                                            |
-| ----------------- | --------------------------------------------------- |
-| `ARCHITECTURE.md` | System design, module boundaries, data flow         |
-| `SCHEMA.md`       | Predicate inventories, class counts, endpoint roles |
-| `DEBUGGING.md`    | Documented bugs with root causes and fixes          |
-| `CONVENTIONS.md`  | Coding standards, endpoint selection rules          |
-| `changelog/`      | Weekly changelogs (`YYYY-Www.md`)                   |
-| `plans/`          | Feature planning: `drafts/` → `active/` → `done/`   |
+| File                | Contents                                                        |
+| ------------------- | --------------------------------------------------------------- |
+| `ARCHITECTURE.md`   | System design, module boundaries, data flow                     |
+| `SCHEMA.md`         | Predicate inventories, class counts, endpoint roles             |
+| `QUERY-MATRIX.md`   | Every query shape, measured — plus the error catalogue (Part 4) |
+| `health/STATUS.md`  | Weekly dashboard health: working, timings, row-count drift       |
+| `query-matrix/`     | One CSV per sweep, dated, with a generated index                |
+| `DEBUGGING.md`      | Documented bugs with root causes and fixes                      |
+| `CONVENTIONS.md`    | Coding standards, endpoint selection rules                      |
+| `wiki/`             | One page per filter dropdown; source of truth for the GitHub Wiki |
+| `queries/`          | Write-ups of individual real questions                          |
+| `changelog/`        | Weekly changelogs (`YYYY-Www.md`)                               |
+| `plans/`            | Feature planning: `drafts/` → `active/` → `done/`               |