This note documents the densest route-adjacent validation surfaces in svc-tenders after Cleanup Sprint 25:

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

The goal is validation literacy:

• what is request parsing
• what is auth/visibility
• what is mutation gating
• what is readiness/state-machine validation
• what is evidence validation
• what is stricter KES ingress validation

Labels used here:

• VERIFIED
• REAL
• TRANSITIONAL

registerTenderDeclarationRoutes.ts

Route module:

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

Support dependencies:

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

Validation cluster: admin read

Purpose:

• declaration visibility and lookup

Type:

• auth / principal visibility validation

Checks:

• locator validation (tenderId)
• auth context presence
• broader visibility gate:
  • support.canCheckTenderDeclaration(...)
• repository existence check

Broader vs stricter:

• broader than mutation paths

Validation cluster: draft authoring

Purpose:

• create/update draft declaration state

Type:

• request parsing
• auth
• mutation capability
• readiness derivation

Checks:

• schema parse:
  • createTenderDeclarationDraftSchema
  • updateTenderDeclarationDraftSchema
• auth context presence
• mutation capability:
  • support.hasTenderDeclarationCapability(..., "tender:create-draft")
• repository existence/state checks
• form normalization:
  • normalizeTenderDeclarationFormData(...)
• readiness/preview derivation:
  • buildTenderDeclarationValidationResult(...)
  • buildTenderDeclarationPreviewResult(...)

Support helpers involved:

• capability derivation helpers from declaration support

Validation cluster: readiness / declare transitions

Purpose:

• readiness check, mark-ready transition, final declare transition

Type:

• parsing
• auth
• broader vs stricter gating
• declaration readiness checks
• state-machine validation

Checks:

• readiness check:
  • checkTenderDeclarationReadinessSchema
  • broader visibility gate via canCheckTenderDeclaration(...)
• mark-ready:
  • markTenderDeclarationReadySchema
  • stricter mutation gate tender:mark-ready
  • readiness recomputation
  • state-machine guard canMarkTenderReady(...)
• declare:
  • declareTenderSchema
  • stricter mutation gate tender:declare
  • command normalization + declareTenderCommandSchema
  • readiness recomputation
  • state-machine guard canDeclareTender(...)

Broader vs stricter:

• readiness check uses broader visibility
• mark-ready/declare use narrower mutation capabilities plus state-machine guards

Validation cluster: evidence surface

Purpose:

• upload, list, and download declaration evidence

Type:

• auth
• evidence parsing/validation
• upload validation

Checks:

• locator validation
• auth context presence
• upload:
  • broader declaration visibility gate
  • declaration state must be DRAFT
  • shell-owned upload runner
  • evidence file presence
  • support.parseTenderDeclarationEvidenceGroupKey(...)
• list/download:
  • broader visibility gate
  • declaration/evidence existence checks

Support helpers involved:

• runMulterSingle(...)
• parseTenderDeclarationEvidenceGroupKey(...)
• parseOptionalString(...)

Notes:

• evidence upload is stricter than evidence read because it adds the DRAFT state gate

registerAuctionDeclarationRoutes.ts

Route module:

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

Support dependencies:

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

Transitional note:

• validation runs over a composed repository surface that mixes declaration methods and output-allocation methods

Validation cluster: output allocation admin surface

Purpose:

• manage output allocations colocated with auction declaration admin routes

Type:

• parsing
• auth
• mutation capability

Checks:

• schema parse:
  • createOutputAllocationSchema
  • updateOutputAllocationSchema
• auth context presence
• broader read gate for reads:
  • canCheckAuctionDeclaration(...)
• narrower write gate for writes:
  • hasAuctionDeclarationCapability(..., "auction:create-draft")
• allocation normalization:
  • normalizeOutputAllocationFormData(...)

Broader vs stricter:

• reads use broader visibility
• writes use narrower mutation capability

Validation cluster: declaration read / draft authoring

Purpose:

• read and author auction declaration drafts

Type:

• parsing
• auth
• mutation capability
• readiness derivation

Checks:

• read path uses broader canCheckAuctionDeclaration(...)
• draft authoring uses:
  • schema parse
  • auth
  • auction:create-draft
  • form normalization
  • optional allocation existence check
  • readiness/preview derivation

Support helpers involved:

• auction capability derivation helpers from declaration support

Validation cluster: readiness / announce transitions

Purpose:

• readiness assessment, mark-ready transition, final announce/declare transition

Type:

• parsing
• auth
• broader vs stricter gating
• declaration readiness checks
• state-machine validation

Checks:

• readiness check:
  • checkAuctionDeclarationReadinessSchema
  • broader visibility gate
• mark-ready:
  • markAuctionDeclarationReadySchema
  • stricter mutation gate auction:mark-ready
  • readiness recomputation
  • state-machine guard canMarkReady(...)
• declare:
  • declareAuctionAnnouncementSchema
  • stricter mutation gate auction:declare
  • command normalization + declareAuctionCommandSchema
  • readiness recomputation
  • state-machine guard canDeclareAuction(...)

Broader vs stricter:

• broader read/check visibility
• stricter mark-ready/declare mutation gates

Validation cluster: evidence surface

Purpose:

• upload, list, and download auction declaration evidence

Type:

• auth
• evidence parsing/validation
• upload validation

Checks:

• locator validation
• auth context presence
• upload:
  • stricter auction:create-draft mutation gate
  • declaration state must be DRAFT
  • shell-owned upload runner
  • evidence file presence
  • support.parseAuctionDeclarationEvidenceGroupKey(...)
• list/download:
  • broader visibility gate
  • declaration/evidence existence checks

Notes:

• upload is stricter than list/download
• the module stays transitional because it validates over a composed repository surface

registerKesRoutes.ts

Route module:

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

Support dependencies:

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

Transitional note:

• repository input still comes from the mixed root repository

Validation cluster: general case/action parsing

Purpose:

• parse action payloads and identifiers for KES case lifecycle endpoints

Type:

• request parsing/shape validation
• auth

Checks:

• locator parsing via parseOptionalString(...)
• auth via requireServiceAuth
• schema parsing per endpoint, for example:
  • createKesOrchestratorCaseSchema
  • approveKesOrchestratorLandownerSchema
  • publishKesOrchestratorAuctionSchema
  • confirmKesOrchestratorFundingSchema
  • assignKesOrchestratorTaskSchema
  • submitKesOrchestratorInspectionSchema
  • closeKesOrchestratorCaseSchema

Notes:

• most of these flows rely on repository/state validation after schema/auth checks

Validation cluster: operator read / control-plane parsing

Purpose:

• parse query filters for list/control-plane/suggestion surfaces

Type:

• parsing

Checks:

• page/limit parsing
• state/role parsing
• stakeholder/query parsing

Support helpers involved:

• parser helpers from kesRouteSupport.ts
• route-local parsers:
  • parseKesOrchestratorListOptions(...)
  • parseKesRole(...)
  • parseKesCaseState(...)

Validation cluster: process-map mutation

Purpose:

• validate process-map write payloads

Type:

• parsing
• auth

Checks:

• auth
• upsertKesOrchestratorProcessMapSchema

Notes:

• this path does not add stricter ingress/security validation

Validation cluster: payment-sensitive ingress

Purpose:

• handle the stricter KES payment-related validation paths

Type:

• parsing
• auth
• ingress/security validation
• payment-sensitive stricter validation

Checks:

1. payment request

• requestKesOrchestratorPaymentSchema
• auth
• support.ensureThirdPartyKycBoundary(...)
• support.verifyIncomingSignatureGate(...)

2. payment approve

• approveKesOrchestratorPaymentSchema
• auth
• support.verifyIncomingSignatureGate(...)

3. payment settle

• settleKesOrchestratorPaymentSchema
• auth
• support.verifyIncomingSignatureGate(...)

Broader vs stricter:

• broader KES actions use auth + schema validation only
• payment-sensitive paths add signature verification
• payment request is the strictest path because it also adds the KYC boundary helper

Honest asymmetry

VERIFIED

These validation surfaces are not symmetric, and that is correct:

• tender declarations and auction declarations both combine schema parsing, auth, capability derivation, readiness recomputation, and evidence parsing
• auction declarations additionally validate over unresolved output-allocation composition
• KES uses a different pattern:
  • many endpoints are schema + auth + repository/state validation
  • payment-sensitive endpoints add the stricter ingress layer

Trying to flatten these into one generic validation story would hide the real topology.