Butkhuzi Runtime Bootstrap

Runtime location

The new copy-first Butkhuzi runtime now lives at:

• services/svc-butkhuzi/package.json
• services/svc-butkhuzi/src/server.ts

Canonical intended dev runtime target:

• http://localhost:4024

Bootstrap and server entry

Core bootstrap files:

• services/svc-butkhuzi/package.json
• services/svc-butkhuzi/tsconfig.json
• services/svc-butkhuzi/src/server.ts
• services/svc-butkhuzi/src/config.ts
• services/svc-butkhuzi/src/db.ts
• services/svc-butkhuzi/src/auth.ts
• services/svc-butkhuzi/src/http/authTypes.ts

The runtime follows the same extracted-service pattern already used by ICPI, accommodations, and vacancies:

• local config/env loading
• local DB pool
• copied auth ingress that preserves existing bearer-token plus /auth/me principal resolution behavior
• local route registration for the Butkhuzi HTTP surface

Files copied into the new runtime

Copied Butkhuzi-owned package:

• services/svc-butkhuzi/src/butkhuzi/contracts.ts
• services/svc-butkhuzi/src/butkhuzi/validation.ts
• services/svc-butkhuzi/src/butkhuzi/repository.ts
• services/svc-butkhuzi/src/routes/registerButkhuziRoutes.ts
• services/svc-butkhuzi/src/routes/support/butkhuziRouteSupport.ts

Extra bootstrap files added because the new runtime needs them to start independently:

• config/env loader
• DB pool creator
• auth ingress module
• HTTP auth types
• service package metadata and TS config

What remains shared

Shared on purpose:

• services/api/src/routes/butkhuzi.ts
• BUTKHUZI_SERVICE_URL ?? TENDERS_SERVICE_URL
• shared gateway auth behavior
• shared service auth/principal resolution semantics behind /auth/me

These remain outside the Butkhuzi runtime because this sprint is bootstrap creation, not gateway/auth boundary change.

What stayed old-host-only

Still old-host-only in this sprint:

• live Butkhuzi hosting in services/svc-tenders/src/server.ts
• root repository compatibility delegation in services/svc-tenders/src/repository.ts
• canonical Butkhuzi migrations in services/svc-tenders/migrations/0009 through 0012

Why:

• rollback and parity hosting still need the old host intact
• migration ownership has not been transferred yet

Coexistence and rollback notes

Current mode:

• copy-first coexistence
• old host remains active
• new runtime is opt-in only for now

Root helper scripts added:

• package.json predev:butkhuzi
• package.json dev:butkhuzi
• package.json dev:api:butkhuzi-extracted

Port cleanup awareness added:

• scripts/dev-bootstrap.js now includes 4024

Rollback remains simple because:

• the API gateway still defaults Butkhuzi to TENDERS_SERVICE_URL unless BUTKHUZI_SERVICE_URL is explicitly set
• old Butkhuzi hosting in svc-tenders was not removed

Verification notes

Build:

• npm --prefix services/svc-butkhuzi run build passed

Startup sanity:

• the runtime emitted svc-butkhuzi running on http://localhost:4124
• Windows-side health probe returned 200 {"ok":true} on temporary verification port 4124

Port note:

• 4024 remains the canonical intended dev target
• 4124 was used only for this sprint’s startup proof because 4024 was already occupied in the local shell environment