osm cockpit: name the codebook failure that draws a grey map

[AdaWorldAPI]

What

Adds GET /api/osm/health — one read that says why the map looks the way it does: slab path/rows/digest, and for each sidecar the file state and the loaded state, reported separately.

Two pure helpers (sidecar_path, styling_verdict) + the handler + two tests. No change to any render or query path.

Why

A missing or unreadable .books sidecar is invisible from outside. Without it open_books() yields None, query_tile_shapes takes its .unwrap_or(ShapeClass::Other) arm, and every shape classes as Other — fill:'none' plus a thin grey stroke. The server still answers 200 with a full tile of correct geometry, so no status code, no error, and no log line distinguishes it from a working map.

Four different causes produce that identical screen: unset env, absent file, foreign bake (digest mismatch), outdated format. Telling them apart previously meant a git bisect.

The file/loaded split matters because those two disagree in exactly the interesting case — present but refused — which is the difference between "ship the missing file" and "re-bake the region". styling_verdict names the next action rather than the state, since books: false alone doesn't say which job to do.

Measured against production while writing this

• z14/8802/5373 returns 6,508 shapes, 100% other — on both the binary and JSON tile endpoints. The class byte is decided once, server-side in query_tile_shapes, so the renderer is not implicated (this was the first hypothesis, and it was wrong).
• /api/osm/feature/1740603 → entity_type: 3842 (osm_way), real ordinal, real geometry, but tags:{} and osm_key:null. Only the books-derived fields are empty; the row and .chains are intact.
• The deployed codebook's header reads OSMCBK\0\x02; this build's MAGIC is OSMCBK\0\x03 (bumped in openstreetmap-website-rs@3142a8d, "label codebook + junction rows", 2026-08-12). It is refused at the magic check, before the digest check runs.
• The slab digests in fact agree (8ec93a6ee63e89d2 in both books and chains headers), so this is an outdated format, not a foreign bake — precisely the distinction these four arms exist to make.

Fix for the live deploy is a re-bake with the current baker; no code change restores it. This PR makes the next occurrence cost one HTTP call instead of a bisect.

Verification

• cargo check -p cockpit-server — passes, exit 0, no new warnings.
• Endpoint behaviour confirmed against the live deployment's actual artifacts (byte-level header reads, above).
• Not run: the test suite. The two added tests (styling_verdict_separates_all_four_states, sidecars_resolve_from_the_slab_stem_not_the_lance_dir) cover pure functions with no I/O, but a test build needs more disk than this container currently has. Flagging rather than implying they passed.
• Scope held to cockpit-server; no workspace build, no xtask verify.

Draft until the tests are actually executed.

---

Generated by Claude Code

Summary by CodeRabbit

• New Features

  • Added an OpenStreetMap health endpoint reporting the status of map data, codebooks, chains, and styling.
  • Health results distinguish between unconfigured, loaded, unavailable, and refused styling configurations.

• Bug Fixes

  • Improved error reporting when required map data files are missing.
  • Added clearer diagnostics and fallback handling when the map data path is not configured.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: fe25e0f3-fd6e-4ea1-a796-36ff51a04b80

📥 Commits

Reviewing files that changed from the base of the PR and between 73ce105 and bd854e7.

📒 Files selected for processing (2)

• crates/cockpit-server/src/main.rs
• crates/cockpit-server/src/osm_features.rs

---

📝 Walkthrough

Walkthrough

The OSM feature module now resolves sidecar files consistently, logs missing-file errors, and exposes /api/osm/health. The endpoint reports slab, sidecar, loading, and styling state. Tests cover styling verdicts and sidecar path derivation.

Changes

OSM health diagnostics

Layer / File(s)	Summary
Shared sidecar resolution and loading crates/cockpit-server/src/osm_features.rs	Sidecar paths derive from OSM_SLAB_PATH. Missing .books and .chains files now produce actionable logs while preserving fallback behavior.
Health endpoint and router wiring crates/cockpit-server/src/osm_features.rs, crates/cockpit-server/src/main.rs	The router exposes /api/osm/health. The handler reports slab metadata, sidecar presence and sizes, loading state, row count, digest, and styling diagnosis.
Health state and path validation crates/cockpit-server/src/osm_features.rs	Tests cover unconfigured, healthy, absent, and refused styling states, plus raw slab stem path resolution.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant osm_health_handler
  participant SidecarFiles
  Client->>osm_health_handler: GET /api/osm/health
  osm_health_handler->>SidecarFiles: Read slab, books, and chains state
  SidecarFiles-->>osm_health_handler: Return loading and styling state
  osm_health_handler-->>Client: Return JSON health response

Loading

Possibly related PRs

• AdaWorldAPI/q2#108: Introduced the osm_features and OSM_SLAB_PATH loading flow extended by this change.

Suggested reviewers: claude

Poem

I’m a rabbit checking slabs at dawn,
Books and chains now leave clues when gone.
Health blooms bright in JSON light,
Four styling verdicts stand upright.
Hop, hop—diagnostics done!

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_779165ca-472a-4910-aafb-9cd999386b79)