Make cross-dating correct + add cloud API (review, science fixes, FastAPI, CI)

[ericgjerde]

What this is

Started as a technical review (docs/TECHNICAL_PLAN.md) and now also implements the high-priority fixes from it: the dating-science correctness bugs, a testing/CI foundation, and a deployable FastAPI service so the engine actually runs in the cloud.

Headline result

On a committed, deterministic synthetic fixture with a known felling year of 1789, the old pipeline returned a confidently wrong 1739 (r=0.89, t=18.7) because RWL master chronologies were built from raw widths, leaving an age-trend that matched spuriously. After the fix it returns the correct 1789, HIGH confidence (r=0.97, t=35.8). That regression is now locked in by an offline end-to-end test.

Science correctness fixes

• Master chronology (§3.3): detrend each series to an index, then take a robust (biweight) mean — not a mean of raw widths. Cached per reference.
• Felling year / bark edge (§3.2): new crossdating/felling.py. Reports now distinguish exact felling year (bark edge), an estimated range (sapwood model), and terminus post quem ("felled after"). The bark_edge flag was previously ignored.
• Orientation (§3.1): canonical oldest→newest enforced end-to-end (normalize_orientation); --orientation bark_to_pith reverses input. Reversed input recovers the same date.
• Gleichläufigkeit (§3.4): the old formula algebraically cancelled to a no-op. Corrected, added a significance test, and folded GLK into the confidence model.
• Detrending spline (§3.6): replaced the ad-hoc scipy spline with the standard Cook & Peters cubic smoothing spline (Whittaker/Reinsch form). Frequency response verified to be 0.5 at the cutoff wavelength.
• Missing/false rings (§3.5): first-cut detect_missing_ring locates a likely missing/extra ring; the matcher surfaces it as an actionable warning. (Full auto-realignment search is left as follow-up.)
• Parsers/cleanup (§3.7–3.8): fixed Tucson writer rounding (was truncating), added a writer↔parser round-trip test, rationalized era filtering to the felling-year window.
• Imaging (§4.2): ring detector now uses a directional gradient instead of abs(), so it no longer double-counts both edges of every ring.

Cloud / infrastructure

• FastAPI service (src/dendro/api/app.py): /health, /references, /date (JSON), /date/csv (upload), /parse. Engine used as a library (no shelling out to the CLI), input validation + size limits, reference index cached at startup. Verified live via uvicorn and via TestClient.
• Dockerfile (serves the API; ships synthetic demo references, mount a real corpus via DENDRO_REFERENCE_DIR), .dockerignore.
• CI workflow (.github/workflows/ci.yml): ruff + pytest on 3.11/3.12, plus a Docker build + /health smoke test.
• Committed deterministic fixtures + generator, so the realistic dating tests run offline in CI instead of skipping.
• Pinned lockfile, ruff config, and a SessionStart hook for web sessions.

Tests

83 tests total; 79 pass offline, 4 real-ITRDB tests skip without downloaded data (NOAA egress is blocked here). New coverage: end-to-end synthetic dating, felling logic, spline frequency response, GLK significance, missing-ring detection, Tucson round-trip, and the API. ruff check is clean.

What's still outstanding (in the plan)

Full missing-ring re-alignment search, the browser measurement workflow (Phase 3, replaces the local matplotlib GUI), a persistent project/database model + job queue (rest of Phase 2), real reference-corpus management, and validation against dplR.

Note on verification

I built a fresh venv and ran the suite, ruff, and a live API server here — all green. I could not exercise the real-ITRDB path (NOAA returns 403 from this environment), which is exactly why the synthetic fixtures exist.

https://claude.ai/code/session_01GtfEShRYVMGCBEK8Xb8hWE