Auction Action Surface Boundary

This document is the Sprint 03 frontend boundary map for auction actions.

It is intentionally code-first and blunt.

Labels used here:

• VERIFIED
• INFERRED
• UNVERIFIED
• REAL
• MIXED
• UI-FIRST
• SHELL
• MISSING

1. Current Web Topology

The auction web surface is now split into four explicit layers:

1. canonicalRead
   • read-consumption boundary for auction pages
2. compatibility
   • explicit public mutation implementation used today
3. session
   • browser-backed local overlays used by the compatibility implementation
4. futureDurable
   • stable mutation interface where a real durable bidder backend should plug in later

2. Module Map

| Layer | Status | Evidence | Purpose | | --- | --- | --- | --- | | canonicalRead | VERIFIED MIXED | apps/web/src/ui/auctions/canonicalRead/portalReadBoundary.ts | Canonical web read-consumption seam for auction list/detail pages. Still receives mixed truth because portal/api.ts can degrade to compatibility or mock data. | | compatibility | VERIFIED UI-FIRST | apps/web/src/ui/auctions/compatibility/sessionAuctionMutationPort.ts | Explicit mutation implementation for the public portal today. This is not durable backend behavior. | | session | VERIFIED UI-FIRST | apps/web/src/ui/auctions/session/bidOverlay.ts, apps/web/src/ui/auctions/session/fulfillmentOverlay.ts, apps/web/src/ui/auctions/session/transportSelectionOverlay.ts | Browser sessionStorage scaffolding for bid, Buy Now, fulfillment, and transport pre-commit state. | | futureDurable | VERIFIED MISSING | apps/web/src/ui/auctions/futureDurable/auctionMutationPort.ts | Stable future mutation seam. Real durable public bidder writes are not implemented yet. |

3. Current Action Routing

Canonical read consumption

VERIFIED MIXED

Auction pages now consume reads through:

• apps/web/src/ui/auctions/canonicalRead/portalReadBoundary.ts

Current consumers:

• apps/web/src/app/[locale]/(portal)/auctions/page.tsx
• apps/web/src/app/[locale]/[country]/(portal)/auctions/page.tsx
• apps/web/src/app/[locale]/(portal)/auctions/[id]/page.tsx
• apps/web/src/app/[locale]/[country]/(portal)/auctions/[id]/page.tsx
• apps/web/src/app/[locale]/(portal)/auctions/[id]/tracking/page.tsx
• apps/web/src/app/[locale]/(portal)/transport/page.tsx

Important limit:

• this is the web app’s canonical read seam
• it is not a guarantee of durable upstream truth
• downstream fallback still exists inside apps/web/src/portal/api.ts

Compatibility mutation surface

VERIFIED UI-FIRST

Public bidder mutations now route through:

• apps/web/src/ui/auctions/compatibility/sessionAuctionMutationPort.ts

Current mutation operations:

• submitBid()
• buyNow()
• selectTransportPreCommit()
• advanceFulfillment()

Current main consumer:

• apps/web/src/portal/components/AuctionDetailClient.tsx

This is intentionally explicit:

• public bidder actions are still compatibility/session-backed today
• the detail page now calls a named compatibility port instead of writing directly to raw session helpers

Session scaffolding

VERIFIED UI-FIRST

Actual session-backed overlay state lives under:

• apps/web/src/ui/auctions/session/bidOverlay.ts
• apps/web/src/ui/auctions/session/fulfillmentOverlay.ts
• apps/web/src/ui/auctions/session/transportSelectionOverlay.ts

Consumers:

• apps/web/src/portal/components/AuctionDetailClient.tsx
• apps/web/src/ui/auctions/AuctionsPortalClient.tsx
• apps/web/src/portal/components/TransportWorkspaceClient.tsx

Legacy wrapper files remain for import stability:

• apps/web/src/ui/auctions/sessionBidState.ts
• apps/web/src/ui/auctions/sessionFulfillmentState.ts
• apps/web/src/ui/auctions/sessionTransportSelectionState.ts

Those wrappers are no longer the implementation home.

Future durable seam

VERIFIED MISSING

The future seam is:

• apps/web/src/ui/auctions/futureDurable/auctionMutationPort.ts

It defines:

• shared action record shapes
• a stable AuctionMutationPort interface
• explicit futureDurableAuctionMutationPort
• explicit DurableAuctionMutationNotImplementedError

This is where a real public durable mutation path should be attached later.

4. What Is Real vs Temporary

VERIFIED REAL

• Internal declaration writes in svc-tenders
• Canonical service reads when upstream truth is available

VERIFIED MIXED

• Auction page reads in the web app
  • because portal/api.ts still has compatibility and mock fallback behavior

VERIFIED UI-FIRST

• Bid submit
• Buy Now
• Winner fulfillment advance
• Transport pre-commit selection

Those are now structurally explicit as compatibility + session behavior.

5. Developer Rules Going Forward

Read rule

• New auction read consumers should go through canonicalRead/portalReadBoundary.ts
• If read truth becomes fully service-backed later, that module is the place to tighten it

Mutation rule

• Do not add public bidder mutations directly into page components
• Do not add public bidder mutations directly into portal/api.ts
• Route public bidder actions through a mutation port

Compatibility rule

• If behavior is session-backed or local, keep it under compatibility/ or session/
• Do not name temporary logic like it is already durable production backend behavior

Future durable rule

• When a real backend write path exists, implement AuctionMutationPort
• Swap the port used by AuctionDetailClient.tsx
• Keep the session compatibility port available only as explicit fallback/demo behavior if still needed

6. Current Boundary Verdict

• canonicalRead is now structurally separated from public mutations
• public mutations are now structurally separated from raw session stores
• session stores are now explicitly grouped under session/
• a future durable seam now exists in code instead of living only as a doc idea

That does not make the public auction action surface durable. It makes the current non-durable reality much harder to misunderstand.