ICPI Code Boundary Hardening

Status: ACTIVE
Sprint: Extraction Prep Sprint 45

Purpose

This document records the first real ICPI code-boundary hardening pass.

The goal of this sprint was not to extract ICPI out of svc-tenders. The goal was to reduce ICPI dependence on mixed root files by moving clearly ICPI-owned contracts and validation into ICPI-owned modules first.

What Moved Into ICPI-Owned Files

Contracts

New file:

• services/svc-tenders/src/icpi/contracts.ts

Moved here:

• ICPI domain-facing value shapes
• ICPI request/input shapes
• ICPI response shapes
• ICPI repository-port contract
• ICPI route-support contract

Most important effect:

• ICPI types are no longer primarily defined inside the mixed root services/svc-tenders/src/repository.ts

Validation

New file:

• services/svc-tenders/src/icpi/validation.ts

Moved here:

• icpiQuarterSchema
• upsertIcpiPriceSchema

Most important effect:

• ICPI route registration no longer imports ICPI validation from the mixed service-wide services/svc-tenders/src/validation.ts

What Dependency Edges Were Reduced

Route module

Updated file:

• services/svc-tenders/src/routes/registerIcpiRoutes.ts

Reduced:

• direct ICPI type dependence on root repository.ts
• direct ICPI validation dependence on mixed validation.ts

Now imports:

• ICPI contracts from src/icpi/contracts.ts
• ICPI validation from src/icpi/validation.ts

Support module

Updated file:

• services/svc-tenders/src/routes/support/icpiRouteSupport.ts

Reduced:

• route-support type dependence on registerIcpiRoutes.ts

Now imports:

• IcpiRouteSupport from src/icpi/contracts.ts

ICPI repository

Updated file:

• services/svc-tenders/src/icpi/repository.ts

Reduced:

• direct ICPI type dependence on mixed root repository.ts

Now imports:

• ICPI contracts from src/icpi/contracts.ts

Root repository

Updated file:

• services/svc-tenders/src/repository.ts

Changed:

• ICPI contracts are no longer primarily defined here
• root repository now imports ICPI contract types from src/icpi/contracts.ts
• root repository re-exports the long-standing ICPI type names for compatibility

Truthful interpretation:

• root hosting was reduced
• root compatibility was not fully removed yet

What Still Depends On Root Or Shell Files

Root compatibility still remains

VERIFIED

Still in services/svc-tenders/src/repository.ts:

• thin ICPI delegation methods to IcpiRepository
• compatibility re-export of existing ICPI type names

Why it remains:

• safe hardening came first
• caller compatibility was preserved

Shell dependencies still remain

VERIFIED

ICPI still consumes shell-owned helpers through buildIcpiRouteSupport(...):

• requireServiceAuth
• parseOptionalInt
• parseOptionalString
• parseOptionalUpper
• parsePositiveNumber
• clampPositiveInt

Why they remain:

• these helpers are still truthfully shell-owned in the current runtime
• this sprint was about contract/schema ownership, not fake auth/parser separation

What Gateway/API Behavior Stayed The Same

VERIFIED

No gateway route shape changed.

Unchanged:

• services/api/src/routes/icpi.ts
• /api/v1/icpi/prices
• /api/v1/icpi/suggest
• /api/v1/icpi/latest/:itemCode
• /api/v1/icpi/estimate
• /api/v1/icpi/upsert

Also unchanged:

• direct svc-tenders /icpi/* route behavior
• ICPI response shape
• ICPI error shape
• ICPI auth behavior

What Is Still Blocking Actual Extraction

Remaining blockers

1. root repository delegation still exists for ICPI compatibility
2. root repository still re-exports ICPI types for compatibility
3. ICPI route support still depends on shell-owned parser/auth helpers
4. ICPI runtime hosting still happens in services/svc-tenders/src/server.ts
5. web ICPI contract types are still duplicated in apps/web/src/portal/api.ts

What is no longer the primary blocker

VERIFIED

These blockers were materially reduced in Sprint 45:

1. mixed root-file type ownership
2. mixed service-wide validation ownership
3. route-local contract ownership spread across non-ICPI files

Practical Outcome

After Sprint 45:

• ICPI contracts now have a real local home
• ICPI validation now has a real local home
• ICPI route/support/repository code depends less on mixed svc-tenders root surfaces
• remaining extraction work is now more honestly about:
  • shell dependency reduction
  • compatibility cleanup
  • extraction package definition

That is a safer starting point for real extraction preparation than Sprint 44.