Butkhuzi Env Cutover Rehearsal

Canonical Target

• Canonical extracted Butkhuzi runtime target: http://localhost:4024

No temporary override port was needed for the Sprint 78 rehearsal. The rehearsal used the canonical target directly.

Env Settings Used

Temporary rehearsal API:

• PORT=4002
• AUTH_SERVICE_URL=http://127.0.0.1:4100
• TENDERS_SERVICE_URL=http://127.0.0.1:4020

Fallback mode:

• BUTKHUZI_SERVICE_URL=http://127.0.0.1:4020

Cutover mode:

• BUTKHUZI_SERVICE_URL=http://127.0.0.1:4024

Rollback mode:

• BUTKHUZI_SERVICE_URL=http://127.0.0.1:4020

Cutover Steps

1. Started old host on :4020.
2. Started extracted svc-butkhuzi on :4024.
3. Started temporary API on :4002 with BUTKHUZI_SERVICE_URL=http://127.0.0.1:4020.
4. Verified fallback-mode gateway responses on:
   • GET /api/v1/butkhuzi/norms?page=1&pageSize=1
   • GET /api/v1/butkhuzi/suggest?query=SNIP&limit=2
   • GET /api/v1/butkhuzi/search?query=SNIP&page=1&pageSize=2
   • POST /api/v1/butkhuzi/upsert without bearer token
   • POST /api/v1/butkhuzi/chunks/rebuild with bearer token
5. Stopped the temporary API on :4002.
6. Restarted the temporary API on :4002 with BUTKHUZI_SERVICE_URL=http://127.0.0.1:4024.
7. Re-ran the same gateway checks.

Rollback Steps

1. Stopped the temporary cutover API on :4002.
2. Restarted the temporary API on :4002 with BUTKHUZI_SERVICE_URL=http://127.0.0.1:4020.
3. Re-checked GET /api/v1/butkhuzi/norms?page=1&pageSize=1.
4. Confirmed fallback behavior resumed cleanly.

Observations

• Gateway route shape stayed unchanged.
• Auth behavior stayed unchanged.
• Fallback-mode gateway results matched the old host.
• Cutover-mode gateway results matched the extracted host.
• Rollback succeeded with a simple env-target flip plus API restart.
• Canonical target clarity is now explicit: http://localhost:4024 is the correct extracted-runtime dev target.

Remaining Risks

• Sprint 78 was still a controlled rehearsal on a temporary API instance, not a live gateway cutover.
• Migration ownership and legacy-host retirement were intentionally out of scope.
• Parity is verified for the grounded route set above; full live cutover confidence still belongs in the next sprint.