API Auction Mutation Ownership Status

Date: 2026-03-19 Sprint: Platform Cleanup Sprint 103

Scope

This document classifies the auction mutation routes that still live in services/api.

It is about current ownership truth. It is not a claim that these routes are already durable upstream auction actions.

Current Route / Action Inventory

| Route | Local action | Classification | Current backend truth | Verified in-repo caller status | | --- | --- | --- | --- | --- | | POST /api/v1/auctions/create | createAuctionFromLandKes | temporary gateway-local compatibility action | API-local auction engine in localEngineRoutes.ts + engine.ts | no verified direct in-repo caller | | POST /api/v1/auctions/:id/announce | announceAuction | temporary gateway-local compatibility action | same local engine | no verified direct in-repo caller | | POST /api/v1/auctions/:id/open | openBidding | temporary gateway-local compatibility action | same local engine | no verified direct in-repo caller | | POST /api/v1/auctions/:id/bids | submitBid | temporary gateway-local compatibility action | same local engine | no verified direct in-repo caller | | POST /api/v1/auctions/:id/close | closeBidding | temporary gateway-local compatibility action | same local engine | no verified direct in-repo caller | | POST /api/v1/auctions/:id/award | awardWinner | temporary gateway-local compatibility action | same local engine | no verified direct in-repo caller | | POST /api/v1/auctions/:id/settle | confirmSettlement | temporary gateway-local compatibility action | same local engine | no verified direct in-repo caller |

Canonical vs Compatibility Status

• Canonical upstream auction behavior in services/api is still read-oriented:
  • GET /api/v1/auctions
  • GET /api/v1/auctions/:id
• Those reads try upstream first through auctions/gateway.ts and only then fall back to the gateway-local engine.
• The mutation routes above do not proxy to a canonical upstream auction action service.
• They execute against the API-local auction engine and should therefore be treated as compatibility-only action surface, not canonical durable backend ownership.

Why These Routes Still Exist

• They preserve the historical public auction action surface mounted in routes/auctions.ts.
• They provide an API-local compatibility/demo path when no dedicated canonical auction action backend has been wired through the gateway.
• They remain feature-gated by AUCTIONS_LOCAL_ENGINE_ENABLED.

Real Dependency Truth

• The routes depend on:
  • services/api/src/auctions/localEngineRoutes.ts
  • services/api/src/auctions/engine.ts
  • services/api/src/auctions/gateway.ts for enablement and source headers
• They do not currently point at an extracted auction runtime.
• The current public web mutation path does not prove these endpoints are the active bidder path:
  • compatibilityActionAdapter.ts
  • sessionAuctionMutationPort.ts
  • current portal bidder actions are session-backed compatibility behavior, not API-backed durable writes.

Decision

What should remain now

• Keep the auction mutation routes temporarily.
• They are still the mounted compatibility action cluster for the public API surface.
• I found no verified direct in-repo caller, but the routes are still live runtime surface and are documented as compatibility behavior.

What should be isolated next

• Isolate them further as a narrower explicit compatibility package.
• The strongest next cleanup is to keep their public route shape but make the ownership seam even more explicit:
  • gateway route cluster
  • local-engine compatibility implementation
  • later removal/deprecation decision

What may be removable later

• These routes look removable later if both conditions become true:
  • a canonical durable upstream auction action owner is defined
  • no external/runtime consumers still depend on the historical API-local compatibility surface

Current Ownership Verdict

• Ownership today: temporary gateway-local compatibility action
• Not canonical upstream action ownership
• Not extracted service ownership
• Not blocked by gateway/auth concerns
• Best next move: isolate into a narrower compatibility package, not immediate removal

Notes

• The strongest evidence against calling these routes canonical is that the current web bidder path is still session-backed, not API-local-engine-backed.
• Their presence is therefore better understood as historical compatibility surface than as the platform's durable auction action truth.