Purpose

This note documents the support/gate responsibilities of the two densest support modules in svc-tenders after Cleanup Sprint 24:

• services/svc-tenders/src/routes/support/declarationRouteSupport.ts
• services/svc-tenders/src/routes/support/kesRouteSupport.ts

The goal is to make it obvious:

• where capability sets are derived
• where evidence group keys are parsed
• where ingress helpers are surfaced
• where stricter payment/KYC/signature rules actually apply

Labels used here:

• VERIFIED
• REAL
• TRANSITIONAL

declarationRouteSupport.ts

Support module:

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

Consumed by route modules:

• services/svc-tenders/src/routes/registerTenderDeclarationRoutes.ts
• services/svc-tenders/src/routes/registerAuctionDeclarationRoutes.ts

Status:

• VERIFIED
• TRANSITIONAL

Why transitional:

• consumes shared shell-owned auth and upload inputs
• but declaration-local capability derivation and evidence parsing now live here

Helper cluster: capability derivation

Purpose:

• normalize principal permissions into declaration-specific capabilities

Helpers:

• getTenderDeclarationCapabilities(...)
• hasTenderDeclarationCapability(...)
• canCheckTenderDeclaration(...)
• getAuctionDeclarationCapabilities(...)
• hasAuctionDeclarationCapability(...)
• canCheckAuctionDeclaration(...)

What it does:

• maps broad permission strings such as *, admin:*, tender:*, auction:*
• produces narrow declaration capability sets:
  • draft
  • mark-ready
  • declare

Broader vs stricter gate note:

• broader check gates:
  • canCheckTenderDeclaration(...)
  • canCheckAuctionDeclaration(...)
• stricter mutation gates:
  • hasTenderDeclarationCapability(...)
  • hasAuctionDeclarationCapability(...)

This distinction matters because declaration read/check endpoints are intentionally broader than state-changing endpoints.

Helper cluster: evidence-group parsing

Purpose:

• validate route payload group keys against known declaration evidence buckets

Helpers:

• parseTenderDeclarationEvidenceGroupKey(...)
• parseAuctionDeclarationEvidenceGroupKey(...)

What it does:

• accepts only known group keys
• rejects free-form input by returning undefined

Tender evidence groups:

• supportingDocuments
• specificationEvidence
• complianceEvidence

Auction evidence groups:

• supportingDocuments
• qualityEvidence
• subjectEvidence
• transportEvidence

This is intentionally asymmetric because tender and auction declarations do not share the exact same evidence buckets.

Helper cluster: shared shell inputs exposed through the support bundle

Purpose:

• carry shell-owned helpers into declaration routes without keeping declaration-local logic in server.ts

Inputs forwarded:

• requireServiceAuth
• parseOptionalString
• resolveIntentId
• runMulterSingle

Notes:

• resolveIntentId(...) is shared request-intent normalization, not declaration-specific business logic
• runMulterSingle(...) is a declaration upload bridge, but still built from shell-owned upload middleware

kesRouteSupport.ts

Support module:

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

Consumed by route modules:

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

Status:

• VERIFIED
• TRANSITIONAL

Why transitional:

• KES route support still depends on service-shell parser helpers
• KES persistence still sits behind the mixed root repository
• ingress helpers are exposed here, but the route module still decides where stricter rules apply

Helper cluster: shared parser/support forwarding

Purpose:

• expose the parser helpers KES routes need for list/control-plane/action input handling

Helpers forwarded:

• parsePositiveInt
• parseOptionalInt
• parseOptionalString
• parseOptionalUpper
• clampPositiveInt

What it does not do:

• it does not define KES business gating rules
• it only passes shell-level parser behavior through to the route layer

Helper cluster: ingress/security forwarding

Purpose:

• expose stricter ingress helpers used by payment-sensitive KES endpoints

Helpers forwarded:

• ensureThirdPartyKycBoundary(...)
• verifyIncomingSignatureGate(...)

What it does:

• makes the KYC boundary helper available
• makes payload-signature verification available

What it does not do:

• it does not itself decide which endpoints must use them

Stricter vs broader gate note

This is the key distinction for KES:

• broader/auth-only behavior:
  • most KES writes only use requireServiceAuth
• stricter payment-sensitive behavior:
  • payment request uses:
    • requireServiceAuth
    • ensureThirdPartyKycBoundary(...)
    • verifyIncomingSignatureGate(...)
  • payment approve/settle use:
    • requireServiceAuth
    • verifyIncomingSignatureGate(...)

That stricter branching lives in:

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

This is important: kesRouteSupport.ts exposes ingress helpers, but the route module is where stricter payment gating actually becomes active.

Honest asymmetry

VERIFIED

These two support modules are not symmetric, and that is correct:

• declaration support derives capabilities and parses evidence groups
• KES support mostly forwards shell helpers and ingress/security helpers

Trying to force symmetry here would hide the real support boundary.

Current unresolved/transitional areas

VERIFIED

1. Declaration support still depends on shell-owned auth and upload inputs.

2. KES support still depends on shell-owned parser and ingress helpers.

3. KES route support is structurally clear, but the repository input behind the route remains transitional because KES persistence still lives behind the mixed root repository.