more platform

inventory/reservation.go

@@ -0,0 +1,59 @@
+package inventory
+
+import (
+	"context"
+	"time"
+)
+
+// Value types for inventory reservation — cross-module vocabulary shared by
+// cart, checkout, backoffice, and the inventory service. Moving them here
+// means consumers depend on platform/inventory rather than on the Redis
+// implementation package (go-redis-inventory).
+
+// SKU identifies a single stock-keeping unit.
+type SKU string
+
+// LocationID identifies a geographic stock location (e.g. "se", "no").
+type LocationID string
+
+// CartID identifies a shopping cart — used as the reservation holder key.
+type CartID string
+
+// InventoryReference identifies a specific SKU at a specific location.
+type InventoryReference struct {
+	SKU        SKU
+	LocationID LocationID
+}
+
+// CartReserveRequest is what a caller provides to reserve stock for a cart.
+type CartReserveRequest struct {
+	*InventoryReference
+	CartID   CartID
+	Quantity uint32
+	TTL      time.Duration
+}
+
+// ReservationPolicy is the cross-module seam for inventory reservation.
+// Cart mutations call Reserve on add-to-cart / change-quantity and Release on
+// item removal. Checkout calls Available to validate stock before a payment
+// session, and Release on cancel / destroy. Every implementation behind this
+// interface is free to choose its internal storage (Redis Lua, in-memory map,
+// actor grain, etc.) — the consumer never needs to know.
+//
+// This is the "policy-first seam" from docs/ARCHITECTURE.md:
+// commerce policy lives here; the fast, contended storage lives behind it.
+type ReservationPolicy interface {
+	// Reserve holds qty units of sku at locationID for the caller's cart.
+	// Returns an error if insufficient stock is available.
+	Reserve(ctx context.Context, req CartReserveRequest) error
+
+	// Release frees a prior reservation for the given cart at the given
+	// sku+location. Idempotent: releasing an already-released or expired
+	// reservation is a no-op.
+	Release(ctx context.Context, sku SKU, locationID LocationID, cartID CartID) error
+
+	// Available returns the quantity that can still be reserved right now —
+	// total stock minus all active reservations. Used by checkout to validate
+	// that the cart's items are still reservable before opening a payment session.
+	Available(ctx context.Context, sku SKU, locationID LocationID) (int64, error)
+}