Loading module
Resolving locale, route permissions, and workspace projection.
svc-tenders Validation Surface Map
Purpose
This note documents the densest route-adjacent validation surfaces in svc-tenders after Cleanup Sprint 25:
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
READ 2026-03-28T23:42:21.903Z
READ 2026-03-29T04:52:41.869Z
CORE STRICT SAFE DELETE AFTER RERUN REPORT
PUBLIC | DRAFT | v1.0.0
READ 2026-03-29T03:13:33.020Z
what is stricter KES ingress validation
VERIFIEDREALTRANSITIONAL
registerTenderDeclarationRoutes.ts
Validation cluster: admin read
- declaration visibility and lookup
- auth / principal visibility validation
- locator validation (
tenderId)
- auth context presence
- broader visibility gate:
support.canCheckTenderDeclaration(...)
- repository existence check
- broader than mutation paths
Validation cluster: draft authoring
- create/update draft declaration state
- request parsing
- auth
- mutation capability
- readiness derivation
- schema parse:
createTenderDeclarationDraftSchemaupdateTenderDeclarationDraftSchema
- 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
- readiness check, mark-ready transition, final declare transition
- parsing
- auth
- broader vs stricter gating
- declaration readiness checks
- state-machine validation
- 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(...)
- readiness check uses broader visibility
- mark-ready/declare use narrower mutation capabilities plus state-machine guards
Validation cluster: evidence surface
- upload, list, and download declaration evidence
- auth
- evidence parsing/validation
- upload validation
- 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(...)
- evidence upload is stricter than evidence read because it adds the
DRAFT state gate
registerAuctionDeclarationRoutes.ts
- validation runs over a composed repository surface that mixes declaration methods and output-allocation methods
Validation cluster: output allocation admin surface
- manage output allocations colocated with auction declaration admin routes
- parsing
- auth
- mutation capability
- schema parse:
createOutputAllocationSchemaupdateOutputAllocationSchema
- auth context presence
- broader read gate for reads:
canCheckAuctionDeclaration(...)
- narrower write gate for writes:
hasAuctionDeclarationCapability(..., "auction:create-draft")
- allocation normalization:
normalizeOutputAllocationFormData(...)
- reads use broader visibility
- writes use narrower mutation capability
Validation cluster: declaration read / draft authoring
- read and author auction declaration drafts
- parsing
- auth
- mutation capability
- readiness derivation
- 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
- readiness assessment, mark-ready transition, final announce/declare transition
- parsing
- auth
- broader vs stricter gating
- declaration readiness checks
- state-machine validation
- 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 read/check visibility
- stricter mark-ready/declare mutation gates
Validation cluster: evidence surface
- upload, list, and download auction declaration evidence
- auth
- evidence parsing/validation
- upload validation
- 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
- upload is stricter than list/download
- the module stays transitional because it validates over a composed repository surface
registerKesRoutes.ts
- repository input still comes from the mixed root repository
Validation cluster: general case/action parsing
- parse action payloads and identifiers for KES case lifecycle endpoints
- request parsing/shape validation
- auth
- locator parsing via
parseOptionalString(...)
- auth via
requireServiceAuth
- schema parsing per endpoint, for example:
createKesOrchestratorCaseSchemaapproveKesOrchestratorLandownerSchemapublishKesOrchestratorAuctionSchemaconfirmKesOrchestratorFundingSchemaassignKesOrchestratorTaskSchemasubmitKesOrchestratorInspectionSchemacloseKesOrchestratorCaseSchema
- most of these flows rely on repository/state validation after schema/auth checks
Validation cluster: operator read / control-plane parsing
- parse query filters for list/control-plane/suggestion surfaces
- 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
- validate process-map write payloads
- auth
upsertKesOrchestratorProcessMapSchema
- this path does not add stricter ingress/security validation
Validation cluster: payment-sensitive ingress
- handle the stricter KES payment-related validation paths
- parsing
- auth
- ingress/security validation
- payment-sensitive stricter validation
requestKesOrchestratorPaymentSchema- auth
support.ensureThirdPartyKycBoundary(...)support.verifyIncomingSignatureGate(...)
approveKesOrchestratorPaymentSchema- auth
support.verifyIncomingSignatureGate(...)
settleKesOrchestratorPaymentSchema- auth
support.verifyIncomingSignatureGate(...)
- 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
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.