This document is the Sprint 02 auction truth map.

Rules used here:

• VERIFIED: proven directly in code
• INFERRED: likely from code shape, but not fully proven end-to-end
• UNVERIFIED: not proven
• REAL: durable canonical backend path exists
• MIXED: real and non-canonical paths coexist
• UI-FIRST: browser/session/UI behavior is the effective implementation
• SHELL: shape exists, but operational depth is weak
• MISSING: no trustworthy implementation found

Capability Matrix

| Capability | Truth | State | Canonical source of truth | Evidence | Reality note | | --- | --- | --- | --- | --- | --- | | Public list/read | VERIFIED | MIXED | services/svc-tenders GET /auctions backed by Postgres auctions + auction_declarations | services/svc-tenders/src/server.ts app.get("/auctions"); services/svc-tenders/src/repository.ts listAllAuctions, countAllAuctions, LEFT JOIN auction_declarations; services/api/src/routes/auctions.ts; services/api/src/auctions/gateway.ts | Public reads are canonical only when the gateway successfully proxies to svc-tenders. The gateway can still fall back to the local compatibility engine. | | Public detail/read | VERIFIED | MIXED | services/svc-tenders GET /auctions/:id backed by Postgres auctions + auction_declarations | services/svc-tenders/src/server.ts app.get("/auctions/:id"); services/svc-tenders/src/repository.ts findAuctionById; services/api/src/routes/auctions.ts | Same split as list/read: canonical if proxied upstream, compatibility if the gateway falls back. | | Internal declaration list/read | VERIFIED | REAL | services/svc-tenders internal admin routes | services/svc-tenders/src/server.ts app.get("/admin/auctions"), app.get("/admin/auctions/:id"), app.get("/admin/auctions/declarations/:id"); services/svc-tenders/src/repository.ts listInternalAuctions, findInternalAuctionById, findAuctionDeclarationById | This is the cleanest auction read surface in the repo. It is capability-gated and service-backed. | | Create draft / declaration authoring | VERIFIED | REAL | auction_declarations table plus registry projection in auctions | apps/web/src/ui/auctions/announcement/client.ts createAuctionDeclarationDraft; apps/web/src/app/api/auctions/declarations/drafts/route.ts; services/svc-tenders/src/server.ts POST /admin/auctions/declarations/drafts; services/svc-tenders/src/repository.ts createAuctionDeclarationDraft, upsertAuctionRegistryStateFromDeclaration | Durable. This is the real auction creation path in the current repo, but it is an internal/admin declaration flow, not a public bidder-facing action flow. | | Mark ready / declare / announce | VERIFIED | REAL | auction_declarations, auction_declaration_events, registry projection row in auctions | apps/web/src/ui/auctions/announcement/client.ts markAuctionDeclarationReady, declareAuctionAnnouncement; apps/web/src/app/api/auctions/declarations/[id]/declare/route.ts; services/svc-tenders/src/server.ts POST /admin/auctions/declarations/:id/mark-ready, POST /admin/auctions/declarations/:id/declare; services/svc-tenders/src/repository.ts markAuctionDeclarationReady, declareAuction, insertAuctionDeclarationEvent | Durable and transactionally written inside svc-tenders. This is the real state-transition path for announcement, not the public gateway /announce local engine route. | | Public create action surface (/api/v1/auctions/create) | VERIFIED | MIXED | No canonical durable owner found | services/api/src/auctions/localEngineRoutes.ts router.post("/create"); services/api/src/auctions/engine.ts createAuctionFromLandKes | Exists and runs, but only against the gateway-local compatibility engine. It is not the durable canonical auction creation path. | | Public bid submit | VERIFIED | UI-FIRST | No durable public source of truth | apps/web/src/portal/components/AuctionDetailClient.tsx handleBid; apps/web/src/ui/auctions/sessionBidState.ts appendSessionAuctionBid; services/api/src/auctions/localEngineRoutes.ts router.post("/:id/bids") | The current user-facing bid flow does not call a durable backend. It writes to browser sessionStorage. A compatibility gateway bid route exists, but the main portal flow is not using it as canonical truth. | | Public bid state updates in list/detail UI | VERIFIED | MIXED | Base read comes from service or fallback; visible updates are overlaid in browser session state | apps/web/src/ui/auctions/sessionBidState.ts overlayAuctionPortalItem; apps/web/src/ui/auctions/AuctionsPortalClient.tsx session overlay reads/subscriptions; apps/web/src/portal/components/AuctionDetailClient.tsx session sync/subscriptions | The UI can look stateful and coherent, but it is not a single durable read model. Canonical service reads and session overlays are mixed together. | | Winner selection as public action | VERIFIED | MIXED | No canonical public durable route found | services/api/src/auctions/localEngineRoutes.ts router.post("/:id/award") | Public winner selection currently exists only as a local-engine compatibility route. That is executable, but not durable platform truth. | | Settlement recording / entitlement creation | VERIFIED | REAL | auctions table in svc-tenders, mirrored to linked tenders record when present | services/svc-tenders/src/repository.ts settleAuction; services/svc-tenders/src/repository.ts SELECT ... FOR UPDATE, entitlement_id reuse/backfill logic | Durable. This is the strongest post-award auction write in the current backend. It is not the same thing as a public winner-selection API. | | Fulfillment transition | VERIFIED | UI-FIRST | No durable backend source of truth | apps/web/src/ui/auctions/sessionFulfillmentState.ts; apps/web/src/ui/auctions/sessionTransportSelectionState.ts; apps/web/src/portal/components/AuctionDetailClient.tsx fulfillment and transport selection handlers | Winner fulfillment and transport choice are intentionally session-local today. They can look workflow-like, but they are not durable backend state. | | Analytics / history | VERIFIED | SHELL | Declaration event log exists; public portal history does not | services/svc-tenders/src/repository.ts auction_declaration_events; services/svc-tenders/migrations/0032_auction_declaration_v1.sql; apps/web/src/portal/api.ts auditTrail: [] | There is real internal declaration history, but the public portal detail currently exposes an empty audit trail. Do not overstate public auction history as operational. | | Notifications / events | VERIFIED | SHELL | Internal declaration event table only | services/svc-tenders/src/repository.ts insertAuctionDeclarationEvent; services/svc-tenders/src/repository.ts eventType: "AUCTION_READY_FOR_ANNOUNCEMENT" and eventType: "AUCTION_DECLARED" | There is evidence of durable declaration-event logging. I did not verify an auction-specific Kafka/outbox/consumer chain equivalent to KES. Treat auction eventing as partial, not fully event-driven. |

Public Auction Truth, Bluntly

VERIFIED

• Public auction reads can be real.
  • Canonical path: apps/web -> services/api /api/v1/auctions -> services/svc-tenders /auctions.
• Public auction actions are not durably real yet.
  • Bid submit in the live portal is sessionStorage backed.
  • Buy Now in the live portal is sessionStorage backed.
  • Winner fulfillment intent is sessionStorage backed.
  • Transport selection is sessionStorage backed.
• Gateway-local action routes still exist under the public auctions router.
  • They are compatibility behavior, not durable domain truth.

INFERRED

• The repo is intentionally preserving historical auction action surfaces while the durable declaration-backed model is being built out.
• Future AI agents are likely to overread the presence of POST /api/v1/auctions/:id/bids or /award as proof of a durable auction backend. That would be wrong today.

UNVERIFIED

• Auction-specific notifications sent to users.
• Auction-specific Kafka projection consumers comparable to KES.
• A public durable bid ledger outside the declaration/admin workflow.

Current Canonical Owner

For auction truth today, the cleanest owner is:

• Read truth: services/svc-tenders
• Internal declaration write truth: services/svc-tenders
• Public bidding/winner UX truth: currently not durable; effective truth lives in web session overlays plus gateway compatibility behavior

That split is the core fact this sprint is hardening.