fix: OpenAPI spec accuracy — hide internal endpoints, mark signup/verify deprecated

- Remove @openapi annotations from /v1/billing/webhook (Stripe-internal)
- Remove @openapi annotations from /v1/billing/success (browser redirect)
- Mark /v1/signup/verify as deprecated (returns 410)
- Add 3 TDD tests in openapi-spec.test.ts
- Update 2 existing tests in app-routes.test.ts
- 530 tests passing (was 527)

dist/services/keys.js

@@ -100,7 +100,26 @@ export async function downgradeByCustomer(stripeCustomerId) {
         await queryWithRetry("UPDATE api_keys SET tier = 'free' WHERE stripe_customer_id = $1", [stripeCustomerId]);
         return true;
     }
-    return false;
+    // DB fallback: key may exist on another pod's cache or after a restart
+    logger.info({ stripeCustomerId }, "downgradeByCustomer: cache miss, falling back to DB");
+    const result = await queryWithRetry("SELECT key, tier, email, created_at, stripe_customer_id FROM api_keys WHERE stripe_customer_id = $1 LIMIT 1", [stripeCustomerId]);
+    if (result.rows.length === 0) {
+        logger.warn({ stripeCustomerId }, "downgradeByCustomer: customer not found in cache or DB");
+        return false;
+    }
+    const row = result.rows[0];
+    await queryWithRetry("UPDATE api_keys SET tier = 'free' WHERE stripe_customer_id = $1", [stripeCustomerId]);
+    // Add to local cache so subsequent lookups on this pod work
+    const cached = {
+        key: row.key,
+        tier: "free",
+        email: row.email,
+        createdAt: row.created_at instanceof Date ? row.created_at.toISOString() : row.created_at,
+        stripeCustomerId: row.stripe_customer_id || undefined,
+    };
+    keysCache.push(cached);
+    logger.info({ stripeCustomerId, key: row.key }, "downgradeByCustomer: downgraded via DB fallback");
+    return true;
 }
 export async function findKeyByCustomerId(stripeCustomerId) {
     // Check DB directly — survives pod restarts unlike in-memory cache