svc-tenders Response Surface Map

Purpose

This note documents the recurring response shapes in the densest svc-tenders route modules after Cleanup Sprint 36.

Focus:

• read/detail payloads
• declaration preview/validation payloads
• evidence payloads
• KES action/detail payloads
• control-plane aggregate payloads

Labels used here:

• VERIFIED
• REAL
• TRANSITIONAL

registerTenderDeclarationRoutes.ts

Route module:

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

Response cluster:

• admin read

Dominant response shape:

• { ok, declaration }

Classification:

• read

Response cluster:

• draft authoring

Dominant response shape:

• { ok, declaration, validation, preview }

Classification:

• write
• preview
• validation

Notes:

• VERIFIED
• the response includes both persisted domain state and derived validation/preview surfaces

Response cluster:

• readiness / declare transitions

Dominant response shape:

• readiness and mark-ready: { ok, declaration, validation, preview }
• declare: { ok, declaration, validation, preview, event }

Classification:

• write
• preview
• validation

Response cluster:

• evidence surface

Dominant response shape:

• upload: { ok, evidence, reference }
• list: { ok, evidence }
• download: stream response, not JSON payload shaping

Classification:

• upload
• read

Notable asymmetry:

• VERIFIED
• evidence upload remains broader-helper plus local-state-guard driven, but its success response is still a compact evidence/reference payload rather than the declaration preview/validation shape

registerAuctionDeclarationRoutes.ts

Route module:

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

Response cluster:

• output-allocation admin surface

Dominant response shape:

• list: { ok, allocations }
• detail/write: { ok, allocation }

Classification:

• read
• write
• transitional

Response cluster:

• admin read

Dominant response shape:

• { ok, declaration }

Classification:

• read

Response cluster:

• evidence surface

Dominant response shape:

• upload: { ok, evidence, reference }
• list: { ok, evidence }
• download: stream response, not JSON payload shaping

Classification:

• upload
• read

Response cluster:

• draft authoring

Dominant response shape:

• { ok, declaration, validation, preview }

Classification:

• write
• preview
• validation
• transitional

Response cluster:

• readiness / announce transitions

Dominant response shape:

• readiness and mark-ready: { ok, declaration, validation, preview }
• declare: { ok, declaration, validation, preview, event }

Classification:

• write
• preview
• validation
• transitional

Notable asymmetry:

• VERIFIED
• auction declarations share the same rich preview/validation response family as tender declarations
• output allocations retain a separate allocation response family in the same module

Unresolved or transitional notes:

• TRANSITIONAL
• this module still mixes declaration response surfaces with output-allocation response surfaces because the route boundary remains composed

registerKesRoutes.ts

Route module:

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

Response cluster:

• case entry

Dominant response shape:

• { ok, caseId, detail }

Classification:

• write
• detail

Response cluster:

• operator read / control-plane surface

Dominant response shape:

• list: { ok, cases, meta }
• detail: { ok, detail }
• projection: { ok, projection }
• process map read: { ok, map }
• control plane: { ok, snapshot }
• suggestions: { ok, suggestions, meta }

Classification:

• read
• aggregate

Response cluster:

• process-map mutation

Dominant response shape:

• { ok, map }

Classification:

• write

Response cluster:

• case / task / inspection actions

Dominant response shape:

• { ok, detail }

Classification:

• action
• detail

Notes:

• VERIFIED
• some create-like KES actions return 201, but the payload family stays detail-oriented

Response cluster:

• payment-sensitive actions

Dominant response shape:

• { ok, detail }

Classification:

• action
• detail
• ingress-sensitive

Response cluster:

• case closure

Dominant response shape:

• { ok, detail }

Classification:

• action
• detail

Notable asymmetry:

• VERIFIED
• KES does not use the declaration validation + preview response family at all
• instead it mixes detail-style action responses with aggregate read surfaces like snapshot, meta, and projection

Unresolved or transitional notes:

• TRANSITIONAL
• KES responses still ride on a root-repository-derived persistence slice rather than a fully isolated child repository

Current Asymmetry

VERIFIED

The dense response surfaces are intentionally different:

• tender and auction declarations share a rich declaration + validation + preview family
• auction declarations additionally expose allocation response payloads in the same module
• KES centers on detail action results and aggregate read payloads instead of preview/validation responses