KES API And Persistence Surface

Current Status Note

This document now describes the current post-extraction KES surface.

• Canonical KES HTTP/runtime host: services/svc-kes
• Retired host: old colocated KES HTTP routing in svc-tenders
• Removed compatibility layer: former services/svc-tenders/src/kes/*
• Shared backbone retained on purpose: services/svc-tenders/src/kafka

Route / API Surface

Stable route surface

• GET /kes-orchestrator/cases
• GET /kes-orchestrator/cases/:id
• GET /kes-orchestrator/cases/:id/projection
• GET /kes-orchestrator/control-plane
• GET /kes-orchestrator/process-map
• GET /kes-orchestrator/suggestions

Classification:

• VERIFIED
• mostly REAL
• mostly KES-owned

Notes:

• These reads are real backend surfaces.
• They are unusual because they are public read clusters inside a dense operational module.
• They are now served by the extracted KES runtime in services/svc-kes/src/routes/registerKesRoutes.ts and services/svc-kes/src/kes/repository.ts.

Transitional route surface

• POST /kes-orchestrator/cases
• PUT /kes-orchestrator/process-map
• POST /kes-orchestrator/cases/:id/approve-landowner
• POST /kes-orchestrator/cases/:id/publish-auction
• POST /kes-orchestrator/cases/:id/confirm-funding
• POST /kes-orchestrator/cases/:id/tasks
• POST /kes-orchestrator/cases/:id/inspections
• POST /kes-orchestrator/cases/:id/close

Classification:

• VERIFIED
• REAL
• MIXED

Why transitional:

• they are real writes
• they rely on shell auth
• they still depend on shared auth ingress plus shared KYC/signature semantics
• they no longer depend on a mixed-root KES repository surface

Stricter ingress / payment-sensitive route surface

• POST /kes-orchestrator/cases/:id/payments/request
• POST /kes-orchestrator/payments/:id/approve
• POST /kes-orchestrator/payments/:id/settle

Classification:

• VERIFIED
• REAL
• MIXED

Why mixed:

• payment request requires auth, KYC-boundary enforcement, and signature verification
• payment approve/settle require auth and signature verification
• write behavior is real and durable
• ingress/security enforcement is still shell-hosted

Verdict:

• these routes already run in the extracted svc-kes runtime, but they still carry shared ingress/security expectations that are intentionally outside full KES independence

Persistence Surface

Clearly KES-owned tables and entities

• kes_orchestrator_cases
• kes_orchestrator_tasks
• kes_orchestrator_inspections
• kes_orchestrator_payments
• kes_orchestrator_events
• kes_orchestrator_process_maps

Classification:

• VERIFIED
• REAL
• KES-owned

Notes:

• these are the clearest KES data surfaces
• they represent case lifecycle, runtime action history, payment state, and process configuration

Shared event-backbone tables tied to KES

• kes_outbox_events
• kafka_consumer_idempotency
• kes_domain_event_projection_events
• kes_domain_event_projection_counters
• kes_domain_event_projection_aggregates

Classification:

• VERIFIED
• REAL
• kafka/orchestrator-shared

Notes:

• KES is the dominant business context here
• but these tables behave like shared event infrastructure, not simple KES-owned CRUD storage

Current persistence hosting

• canonical KES persistence lives in repository.ts
• payment-note encryption and event hash-chain behavior now live in that extracted KES repository and its local security helpers
• the old services/svc-tenders/src/kes/* compatibility layer has been removed
• shared backbone workers still remain in services/svc-tenders/src/kafka

Classification:

• VERIFIED
• REAL
• KES-owned for the HTTP/runtime persistence slice
• kafka/orchestrator-shared for the remaining backbone workers

Ingress / Security Surface

Current KES-specific ingress rules:

• requireServiceAuth(...) for all KES writes
• ensureThirdPartyKycBoundary(...) for payment request
• verifyIncomingSignatureGate(...) for payment request, payment approve, and payment settle

Current hosting:

• server.ts
• adapted through kesRouteSupport.ts

Classification:

• VERIFIED
• REAL
• shared shell / ingress-owned

Extraction note:

• KES host extraction is complete, but these ingress rules are still shared-shell semantics rather than fully KES-local ownership

Kafka / Orchestrator Surface

KES-relevant runtime pieces:

• gateway mutation proxy event publish in kes-orchestrator.ts
• proxy-event consumer in kesEventConsumer.ts
• outbox relay in kesOutboxRelay.ts
• domain-event consumer in kesDomainEventConsumer.ts
• DLQ replay in kesDlqReplay.ts

Classification:

• VERIFIED
• REAL
• kafka/orchestrator-shared

Extraction note:

• KES route/runtime extraction is already complete
• event-worker ownership is still a second boundary decision, not evidence that the extracted KES runtime is incomplete

Recommended Extraction Notes

• KES is already extracted at the HTTP/runtime layer.
• The remaining cleanup is not host extraction; it is backbone/topology clarification.
• The safest next step is shared-backbone clarification or transfer planning, not another route-host move.