Window Goal

Execute the first real env-only ICPI gateway cutover in the current runnable environment by switching only the API gateway target from old colocated ICPI hosting to the extracted svc-icpi runtime.

Constraints held during the window:

• gateway route shape unchanged
• auth behavior unchanged
• old colocated ICPI hosting kept available
• rollback kept as an env flip plus gateway restart

Exact Seam Change Used

Pre-cutover gateway target

• ICPI_SERVICE_URL=http://127.0.0.1:4020
• TENDERS_SERVICE_URL=http://127.0.0.1:4020

Cutover gateway target

• ICPI_SERVICE_URL=http://127.0.0.1:4021
• TENDERS_SERVICE_URL=http://127.0.0.1:4020

Only the ICPI upstream target changed.

No gateway route definitions changed. No gateway auth middleware changed.

Runtime Layout During the Window

• svc-auth on :4100
• old colocated ICPI host via svc-tenders on :4020
• new extracted ICPI host via svc-icpi on :4021
• API gateway on :4001

Pre-Cutover Start Steps

1. free ports 4001, 4020, 4021, 4100
2. start svc-auth
3. start old colocated ICPI host in svc-tenders
4. start new svc-icpi
5. start gateway in fallback mode pointing ICPI at :4020
6. verify fallback readiness before seam flip

Pre-Cutover Checks Run

• old host GET /icpi/prices?page=1&pageSize=1 returned 200
• new host GET /icpi/prices?page=1&pageSize=1 returned 200
• fallback gateway GET /api/v1/icpi/prices?page=1&pageSize=1 returned 200
• fallback gateway authenticated POST /api/v1/icpi/upsert succeeded
• fallback gateway GET /api/v1/icpi/latest/:itemCode read-back succeeded
• fallback gateway missing-token denial still returned 401 missing_bearer_token

Verification item used:

• itemCode: ICPI_S52_MMUXY4ER

Cutover Steps Executed

1. stop only the gateway
2. restart the gateway with:
   • ICPI_SERVICE_URL=http://127.0.0.1:4021
   • TENDERS_SERVICE_URL=http://127.0.0.1:4020
3. leave both old and new ICPI hosts running
4. run immediate post-cutover smoke checks

Smoke Checks Run After Cutover

• GET /api/v1/icpi/prices?page=1&pageSize=1
• GET /api/v1/icpi/suggest?query=cutover&region=GE&limit=5
• POST /api/v1/icpi/upsert with authenticated happy-path payload
• GET /api/v1/icpi/latest/:itemCode?region=GE
• GET /api/v1/icpi/estimate?itemCode=:itemCode&quantity=2&region=GE
• POST /api/v1/icpi/upsert without bearer token

Comparison target after cutover:

• direct new extracted host on :4021

Observations

• the gateway came back cleanly on the extracted ICPI target
• read routes stayed healthy immediately after the seam flip
• authenticated happy-path upsert still returned 200
• persisted read-back matched direct svc-icpi
• estimate route reflected the cutover-write value
• missing-token denial remained 401 missing_bearer_token
• no gateway-specific ICPI anomaly appeared during the checked window

Script-Level Cutover State

To make the cutover real in the current monorepo workflow, the default local gateway seam was updated:

• root package.json dev
• root package.json dev:core
• root package.json dev:api

These now point ICPI to http://localhost:4021.

Rollback remains explicit via:

• root package.json dev:api:icpi-fallback

Port cleanup/bootstrap support was also updated in:

• dev-bootstrap.js

Whether the Cutover Remained In Place

Yes, at the seam/config level.

The gateway default in the current local workflow now points at extracted svc-icpi, and no rollback was needed during the cutover window.

Old colocated ICPI hosting remains available for fallback.

Stop / Window Close Steps

After the observation window and documentation capture:

1. rehearsal processes were stopped
2. the seam remained configured toward svc-icpi
3. fallback remained available through the preserved old host and explicit fallback script