Return a typed 503 DEMO_MODE_UNSUPPORTED for Postgres and Soroban-backed routes when DEMO_MODE is on #1515

Summary

The public deployment runs with DEMO_MODE=true. The README promises that features needing PostgreSQL (metering, billing, invoices, audit persistence, usage exports) "respond with errors in demo mode", and that Stellar/Soroban calls are not made. Nothing enforces either. In demo mode those routes still try to use the Postgres pool (2-second connect timeout, then a 500), the Prisma client, or the Soroban clients, and the response is an opaque INTERNAL_ERROR. This issue adds an explicit demo capability guard: a declared list of routes that are unavailable in demo mode, a stable 503 DEMO_MODE_UNSUPPORTED envelope, and a health field that tells clients which mode they are talking to.

Background and evidence

• What the README promises. README.md, "Demo mode": "Features needing PostgreSQL (metering, billing, invoices, audit persistence, usage exports) respond with errors in demo mode", and "Stellar/Soroban calls are not made."
• The only demo branches.
  • src/db/index.ts, initializeDb (lines 31-34), only switches the SQLite bootstrap: if (process.env.DEMO_MODE === 'true') { bootstrapDemoDb(sqlite, migrationDir); return; }.
  • src/app.ts (line 350) only disables OpenAPI response validation: validateResponses: process.env.DEMO_MODE !== "true".
  • No other code reads DEMO_MODE (grep -rn DEMO_MODE src).
• Postgres still used. src/app.ts (line 180) always sets app.locals.dbPool = pool (src/db.ts, a real pg.Pool with connectionTimeoutMillis). Billing (src/routes/billing/deduct.ts), idempotency, invoices (src/routes/invoices.ts, through Prisma) and forecast all use it in demo mode.
• Soroban still called. createSorobanBillingService builds a client whenever SOROBAN_BILLING_CONTRACT_ID is set, and the README's Vercel instructions set it, so demo traffic can reach a real RPC.
• No mode signal. /api/health returns { status: "ok", service: "callora-backend" } with no indication of demo mode.

Scope

In scope

1. Config. Promote DEMO_MODE into src/config/env.ts (zod boolean) and config.demoMode, replacing the raw process.env reads.
2. Capability guard.
   • Add src/middleware/demoGuard.ts with a declared table of route prefixes and methods that require Postgres or Soroban: /api/billing/*, /api/invoices, /api/usage*, /api/exports*, /api/admin/usage/*, /api/admin/db/explain, /api/vault/deposit/prepare, /api/audit writes, /api/credits, /api/refunds.
   • In demo mode, matching requests get 503 with code: "DEMO_MODE_UNSUPPORTED", details: { feature } and Retry-After omitted. Mount it before those routers.
   • Add the code to docs/error-codes.yaml and run npm run error-codes:generate.
3. No external calls. In demo mode, createSorobanBillingService returns undefined regardless of env, and the Postgres pool is created lazily so it never connects.
4. Health. /api/health includes mode: "demo" | "standard". Update the OpenAPI schema for /api/health.
5. Docs. Update README.md (Demo mode section) with the exact list of unavailable routes.

Out of scope

• Making Postgres features work on SQLite.
• The Vercel handler and bundle (a separate issue).

Design constraints

• One table. The guarded route list is a single exported constant, and a test asserts every entry corresponds to a mounted route, so it cannot rot.
• No effect outside demo. With DEMO_MODE unset, behaviour is byte-for-byte unchanged (snapshot test on /api/health aside from the new field).
• Envelope. The 503 uses errorEnvelope with requestId.

Test plan

Add src/middleware/demoGuard.test.ts and extend tests/integration/health.test.ts, using createApp with DEMO_MODE=true.

Regression proof. Row 1 returns a 500 after the pool timeout on current main.

Acceptance criteria

• No raw process.env.DEMO_MODE reads remain outside src/config.
• Every test-plan row passes.
• npm run lint, npm run typecheck, npm run build (including error-codes:check and validate:openapi) and npm test pass, and CI is green.
• At least 90% line coverage on demoGuard.ts.

Getting started

git checkout -b feat/demo-mode-capability-guard
npm ci && npx prisma generate
DEMO_MODE=true CORS_ALLOW_MISSING_ORIGIN=true npm run dev
curl -i -X POST localhost:3000/api/billing/deduct

Read first: src/db/index.ts, src/db/demo.ts, src/app.ts (lines 160-360), src/services/createSorobanBillingService.ts, and the README "Demo mode" section.

PR requirements

• Link this issue (Closes #<n>).
• Paste the guarded route table and test output with coverage.
• Example commit: feat(demo): add capability guard with typed 503 for unsupported routes.

Priority rationale

Medium. The work is contained, but it makes the public demo behave as documented, stops it from contacting real infrastructure, and gives clients a machine-readable signal instead of opaque 500s.