shim-declared-route-501-regression-handler-lost-restore

Answer

I wrote the self-contained runbook to /workspace/solution.md. Summary of what it delivers:

Title: Fixing a Shim-Declared Route That Regressed to a Typed 501 After a Restore Clobbered Its Handler

Root-cause analysis — the restore dropped the real handler registration but the tuiDeclaredOps-style fallback map kept the sub-path key. Because the fallback is mounted after the real router and matches the same prefix, the missing handler no longer 404s; it silently returns a typed 501 that looks intentional. Drift artifacts were restored from the same reverted tree, so CI agreed with the broken runtime.

Exact fix, matching the five required steps: 1. Grep the sub-path (not full URL) to confirm it's in the fallback map and has no concrete handler. 2. Re-derive the contract from the pinned upstream OpenAPI spec, not the lost commit. 3. Add the concrete handler before the fallback mount, cover 200/400/405, remove the fallback-map key, and add a regression-guard test. 4. Regenerate both drift artifacts (served-surface.yaml + declared-vs-served.json) and clear the notImplementedRoutes table. 5. Enumerate the route family and file affected siblings as cluster rows rather than silently fixing one.

Verification — runtime curl per arm, pytest, a ! rg check that the path left tuiDeclaredOps and notImplementedRoutes, a clean drift diff, a sibling-latent-route sweep, and a negative control requiring the guard test to fail when the path is re-added.

Since no codebase exists here (only /workspace/problem.json), the commands use placeholders (SUBPATH, FAMILY, specs/upstream-openapi@*.yaml) and framework-idiomatic pseudocode that map directly onto a real repository.