Aurora Commerce

# docker-compose.yml
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: dev
      POSTGRES_DB: aurora
    ports: ["5432:5432"]
    volumes: ["pgdata:/var/lib/postgresql/data"]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      retries: 5
volumes: { pgdata: {} }

docker compose up -d
export DATABASE_URL="postgres://postgres:dev@localhost:5432/aurora?sslmode=disable"
psql "$DATABASE_URL" -c "select version();"

CREATE TABLE products (
  id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  name        TEXT    NOT NULL,
  unit_price  BIGINT  NOT NULL CHECK (unit_price >= 0),   -- cents
  stock       INTEGER NOT NULL CHECK (stock >= 0)
);

CREATE TABLE customers (
  id    BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  email TEXT UNIQUE NOT NULL
);

CREATE TABLE orders (
  id              BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  customer_id     BIGINT NOT NULL REFERENCES customers(id),
  total           BIGINT NOT NULL CHECK (total >= 0),
  status          TEXT NOT NULL DEFAULT 'pending',
  idempotency_key TEXT,                                   -- safe-retry key; see the idempotency step
  created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- Partial unique index: many NULLs allowed, but a set key is unique.
CREATE UNIQUE INDEX orders_idem_key ON orders (idempotency_key)
  WHERE idempotency_key IS NOT NULL;

CREATE TABLE order_items (
  order_id    BIGINT NOT NULL REFERENCES orders(id) ON DELETE CASCADE,
  product_id  BIGINT NOT NULL REFERENCES products(id),
  quantity    INTEGER NOT NULL CHECK (quantity > 0),
  unit_price  BIGINT  NOT NULL CHECK (unit_price >= 0),   -- price at purchase
  PRIMARY KEY (order_id, product_id)
);

-- one customer first: orders.customer_id NOT NULL REFERENCES customers(id)
INSERT INTO customers (email) VALUES ('demo@aurora.test')
  ON CONFLICT (email) DO NOTHING;

INSERT INTO products (name, unit_price, stock) VALUES
  ('Aurora Mug', 1499, 50),
  ('Aurora Tee', 2999, 12),
  ('Aurora Sticker Pack', 499, 200);

go mod init github.com/you/aurora-api
go get github.com/jackc/pgx/v5

// cmd/api/main.go
package main

import (
	"cmp"
	"context"
	"encoding/json"
	"errors"
	"log/slog"
	"net/http"
	"os"
	"os/signal"
	"syscall"
	"time"

	"github.com/jackc/pgx/v5/pgxpool"
)

type Product struct {
	ID        int64  `json:"id"`
	Name      string `json:"name"`
	UnitPrice int64  `json:"unitPrice"` // cents; camelCase on the wire
	Stock     int    `json:"stock"`
}

// Store is the contract the handlers consume; checkout/order land on it next.
type Store struct{ pool *pgxpool.Pool }

func (s *Store) Products(ctx context.Context) ([]Product, error) {
	rows, err := s.pool.Query(ctx, `SELECT id, name, unit_price, stock FROM products ORDER BY id`)
	if err != nil { return nil, err }
	defer rows.Close()
	out := []Product{}
	for rows.Next() {
		var p Product
		if err := rows.Scan(&p.ID, &p.Name, &p.UnitPrice, &p.Stock); err != nil { return nil, err }
		out = append(out, p)
	}
	return out, rows.Err()
}

func newRouter(s *Store) *http.ServeMux {
	mux := http.NewServeMux()
	mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, r *http.Request) { _, _ = w.Write([]byte("ok")) })
	mux.HandleFunc("GET /products", func(w http.ResponseWriter, r *http.Request) {
		ps, err := s.Products(r.Context())
		if err != nil { http.Error(w, err.Error(), 500); return }
		writeJSON(w, 200, ps)
	})
	return mux // checkout + orders routes register here in later steps
}

func writeJSON(w http.ResponseWriter, status int, v any) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status)
	_ = json.NewEncoder(w).Encode(v)
}

func main() { if err := run(); err != nil { slog.Error("fatal", "err", err); os.Exit(1) } }

func run() error {
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()
	slog.SetDefault(slog.New(slog.NewJSONHandler(os.Stdout, nil)))

	pool, err := pgxpool.New(ctx, os.Getenv("DATABASE_URL"))
	if err != nil { return err }
	defer pool.Close()

	srv := &http.Server{Addr: ":" + cmp.Or(os.Getenv("PORT"), "8080"), Handler: newRouter(&Store{pool})}
	go func() {
		if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
			slog.Error("listen", "err", err)
		}
	}()
	<-ctx.Done()
	sc, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()
	return srv.Shutdown(sc)
}

export JDBC_DATABASE_URL="jdbc:postgresql://localhost:5432/aurora"
export DB_USER=postgres
export DB_PASSWORD=dev

// build.gradle.kts (key deps)
dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("org.springframework.boot:spring-boot-starter-jdbc")
    runtimeOnly("org.postgresql:postgresql")
}
// application.properties — JDBC URL shape (NOT the Go path's libpq DATABASE_URL):
//   spring.datasource.url=${JDBC_DATABASE_URL:jdbc:postgresql://localhost:5432/aurora}
//   spring.datasource.username=${DB_USER:postgres}
//   spring.datasource.password=${DB_PASSWORD:dev}
//   server.shutdown=graceful

// web/ProductController.kt
@RestController
class ProductController(private val jdbc: JdbcTemplate) {
    data class Product(val id: Long, val name: String, val unitPrice: Long, val stock: Int)

    @GetMapping("/products")
    fun list(): List<Product> = jdbc.query(
        "SELECT id, name, unit_price, stock FROM products ORDER BY id",
    ) { rs, _ -> Product(rs.getLong("id"), rs.getString("name"), rs.getLong("unit_price"), rs.getInt("stock")) }
}

POST /cart/preview
Request:  { "lines": [ { "productId": 1, "quantity": 2 } ] }
Response: { "total": 2998, "lines": [ { "productId": 1, "quantity": 2, "unitPrice": 1499, "lineTotal": 2998 } ] }

-- setup (either session):
UPDATE products SET stock = 1 WHERE id = 1;

-- SESSION A:                          -- SESSION B (run after A's UPDATE, before A commits):
BEGIN;                                 BEGIN;
UPDATE products                        UPDATE products
  SET stock = stock - 1                  SET stock = stock - 1
  WHERE id = 1 AND stock >= 1;           WHERE id = 1 AND stock >= 1;   -- BLOCKS here, waiting on A
-- A sees: UPDATE 1
COMMIT;                                -- B unblocks → sees: UPDATE 0  (the loser)
                                       ROLLBACK;   -- nothing to commit; stock stayed at 0
-- final: SELECT stock FROM products WHERE id = 1;  -> 0, sold exactly once

// idemKey may be ""; if set, a replay returns the original order (handled in POST /checkout).
func (s *Store) Checkout(ctx context.Context, customerID int64, lines []Line, idemKey string) (int64, error) {
	tx, err := s.pool.Begin(ctx)
	if err != nil { return 0, err }
	defer tx.Rollback(ctx) // no-op after a successful Commit

	var total int64
	prices := make([]int64, len(lines))
	for i, l := range lines {
		// guard + decrement + capture price in ONE statement — no second read, no drift
		err := tx.QueryRow(ctx,
			`UPDATE products SET stock = stock - $1
			   WHERE id = $2 AND stock >= $1
			 RETURNING unit_price`, l.Qty, l.ProductID).Scan(&prices[i])
		if errors.Is(err, pgx.ErrNoRows) { // 0 rows updated == insufficient stock (or missing product)
			return 0, fmt.Errorf("product %d: %w", l.ProductID, ErrOutOfStock)
		}
		if err != nil { return 0, err }
		total += prices[i] * int64(l.Qty)
	}

	var key any
	if idemKey != "" { key = idemKey } // NULL when empty so the partial unique index stays happy
	var orderID int64
	if err := tx.QueryRow(ctx,
		`INSERT INTO orders (customer_id, total, idempotency_key) VALUES ($1, $2, $3) RETURNING id`,
		customerID, total, key).Scan(&orderID); err != nil { return 0, err }

	for i, l := range lines {
		if _, err := tx.Exec(ctx,
			`INSERT INTO order_items (order_id, product_id, quantity, unit_price)
			   VALUES ($1, $2, $3, $4)`,
			orderID, l.ProductID, l.Qty, prices[i]); err != nil { return 0, err }
	}
	return orderID, tx.Commit(ctx)
}

class OutOfStockException(productId: Long) : RuntimeException("product $productId out of stock")

@Service
class CheckoutService(private val jdbc: JdbcTemplate) {

    // idemKey may be null; a replay returns the original order (handled in the controller).
    @Transactional
    fun checkout(customerId: Long, lines: List<Line>, idemKey: String?): Long {
        var total = 0L
        val prices = LongArray(lines.size)
        for ((i, l) in lines.withIndex()) {
            // guard + decrement + capture price in ONE statement
            prices[i] = try {
                jdbc.queryForObject(
                    "UPDATE products SET stock = stock - ? WHERE id = ? AND stock >= ? RETURNING unit_price",
                    Long::class.java, l.qty, l.productId, l.qty,
                )!!
            } catch (e: EmptyResultDataAccessException) {
                throw OutOfStockException(l.productId) // 0 rows updated -> rolls the whole tx back
            }
            total += prices[i] * l.qty
        }
        val orderId = jdbc.queryForObject(
            "INSERT INTO orders (customer_id, total, idempotency_key) VALUES (?, ?, ?) RETURNING id",
            Long::class.java, customerId, total, idemKey,
        )!!
        for ((i, l) in lines.withIndex()) {
            jdbc.update(
                "INSERT INTO order_items (order_id, product_id, quantity, unit_price) VALUES (?, ?, ?, ?)",
                orderId, l.productId, l.qty, prices[i],
            )
        }
        return orderId
    }
}

import "github.com/jackc/pgx/v5/pgconn"

type checkoutReq struct {
	CustomerID int64  `json:"customerId"`
	Lines      []Line `json:"lines"`
}

// in newRouter(s):
mux.HandleFunc("POST /checkout", func(w http.ResponseWriter, r *http.Request) {
	var req checkoutReq
	if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<20)).Decode(&req); err != nil {
		writeJSON(w, 422, map[string]string{"error": "invalid_request"}); return
	}
	if req.CustomerID == 0 || len(req.Lines) == 0 {
		writeJSON(w, 422, map[string]string{"error": "invalid_request"}); return
	}
	for _, l := range req.Lines {
		if l.Qty <= 0 { writeJSON(w, 422, map[string]string{"error": "invalid_request"}); return }
	}
	idem := r.Header.Get("Idempotency-Key")

	orderID, err := s.Checkout(r.Context(), req.CustomerID, req.Lines, idem)
	switch {
	case err == nil:
		writeJSON(w, 200, map[string]int64{"orderId": orderID})
	case errors.Is(err, ErrOutOfStock):
		writeJSON(w, 409, map[string]string{"error": "out_of_stock"})
	default:
		var pgErr *pgconn.PgError
		if idem != "" && errors.As(err, &pgErr) && pgErr.Code == "23505" { // duplicate idempotency key
			if id, e := s.orderIDByKey(r.Context(), idem); e == nil { // return the ORIGINAL order
				writeJSON(w, 200, map[string]int64{"orderId": id}); return
			}
		}
		writeJSON(w, 500, map[string]string{"error": "internal"})
	}
})

data class CheckoutReq(val customerId: Long, val lines: List<Line>)

@RestController
class CheckoutController(private val svc: CheckoutService, private val jdbc: JdbcTemplate) {
    @PostMapping("/checkout")
    fun checkout(
        @RequestBody req: CheckoutReq,
        @RequestHeader(value = "Idempotency-Key", required = false) idemKey: String?,
    ): ResponseEntity<Map<String, Any>> {
        if (req.customerId == 0L || req.lines.isEmpty() || req.lines.any { it.qty <= 0 })
            return ResponseEntity.unprocessableEntity().body(mapOf("error" to "invalid_request"))
        return try {
            ResponseEntity.ok(mapOf("orderId" to svc.checkout(req.customerId, req.lines, idemKey)))
        } catch (e: DuplicateKeyException) { // duplicate Idempotency-Key -> return the original order
            val id = jdbc.queryForObject(
                "SELECT id FROM orders WHERE idempotency_key = ?", Long::class.java, idemKey)!!
            ResponseEntity.ok(mapOf("orderId" to id))
        }
    }
}

@RestControllerAdvice
class ApiExceptionHandler {
    @ExceptionHandler(OutOfStockException::class)
    fun outOfStock(e: OutOfStockException) =
        ResponseEntity.status(409).body(mapOf("error" to "out_of_stock"))
    @ExceptionHandler(EmptyResultDataAccessException::class)
    fun notFound(e: EmptyResultDataAccessException) =
        ResponseEntity.status(404).body(mapOf("error" to "not_found"))
}

GET /orders/{id}
200: { "id":4821, "customerId":1, "total":5998, "createdAt":"...",
       "items":[ { "productId":2, "quantity":2, "unitPrice":2999 } ] }
404: { "error":"not_found" }

# Needed only for a read-decide-write that spans multiple rows (e.g. a cart-wide budget check):
for attempt in 1..3:
  BEGIN ISOLATION LEVEL SERIALIZABLE
  ... read the budget, decide, write the lines ...
  COMMIT
  on SQLSTATE 40001 (serialization_failure): retry   # nothing committed, safe to repeat
  on other error: abort

-- shipped in the schema step:
--   orders.idempotency_key TEXT
--   CREATE UNIQUE INDEX orders_idem_key ON orders (idempotency_key) WHERE idempotency_key IS NOT NULL;
-- The flow: header -> Checkout inserts key in-tx -> duplicate hits 23505 -> handler returns the original order.
SELECT id, total, created_at FROM orders WHERE idempotency_key = $1;  -- the duplicate-path lookup

# Go (golang-migrate):              # Spring (Flyway, src/main/resources):
db/migrations/                      db/migration/
  0001_init.up.sql   # tables +       V1__init.sql        # tables + orders_idem_key
  0001_init.down.sql #   idem index   V2__seed.sql        # 1 customer + 3 products
  0002_seed.up.sql   # customer +    # (Flyway runs these automatically on boot)
  0002_seed.down.sql #   products
# apply: migrate -path db/migrations -database "$DATABASE_URL" up

import io.ktor.client.HttpClient
import io.ktor.client.call.body
import io.ktor.client.plugins.contentnegotiation.ContentNegotiation
import io.ktor.client.request.get
import io.ktor.serialization.kotlinx.json.json
import kotlinx.serialization.Serializable

@Serializable
data class Product(val id: Long, val name: String, val unitPrice: Long, val stock: Int)

// baseUrl: from the Android emulator, "http://10.0.2.2:8080" reaches the host's localhost.
val api = HttpClient { install(ContentNegotiation) { json() } }

suspend fun fetchProducts(baseUrl: String): List<Product> =
    api.get("$baseUrl/products").body()

// Money is integer cents end to end; format only for display.
fun formatCents(cents: Long): String = "$%,.2f".format(cents / 100.0)

@Composable
fun CatalogScreen(baseUrl: String) {
    var products by remember { mutableStateOf<List<Product>>(emptyList()) }
    LaunchedEffect(Unit) { products = fetchProducts(baseUrl) }
    LazyColumn { items(products) { p -> ProductRow(p) } }
}

@Composable
fun ProductRow(p: Product) {
    Row(Modifier.fillMaxWidth().padding(16.dp), Arrangement.SpaceBetween) {
        Column {
            Text(p.name, style = MaterialTheme.typography.titleMedium)
            Text(if (p.stock > 0) "In stock" else "Sold out",
                 color = if (p.stock > 0) Color.Unspecified else MaterialTheme.colorScheme.error)
        }
        Text(formatCents(p.unitPrice)) // e.g. "$14.99"
    }
}

// From the Android emulator, "http://10.0.2.2:8080" reaches the host's localhost.
const baseUrl = 'http://10.0.2.2:8080';

class Product {
  final int id;
  final String name;
  final int unitPrice; // integer cents
  final int stock;
  const Product({required this.id, required this.name, required this.unitPrice, required this.stock});
  factory Product.fromJson(Map<String, dynamic> j) =>
      Product(id: j['id'] as int, name: j['name'] as String, unitPrice: j['unitPrice'] as int, stock: j['stock'] as int);
}

// Money is integer cents end to end; format only for display.
String formatCents(int cents) => '\$${(cents / 100.0).toStringAsFixed(2)}';

Future<List<Product>> fetchProducts() async {
  final res = await http.get(Uri.parse('$baseUrl/products'));
  final data = jsonDecode(res.body) as List;
  return data.map((j) => Product.fromJson(j as Map<String, dynamic>)).toList();
}

// in the widget tree:
FutureBuilder<List<Product>>(
  future: fetchProducts(),
  builder: (context, snap) {
    if (!snap.hasData) return const CircularProgressIndicator();
    return ListView(children: [
      for (final p in snap.data!)
        ListTile(
          title: Text(p.name),
          subtitle: Text(p.stock > 0 ? 'In stock' : 'Sold out'),
          trailing: Text(formatCents(p.unitPrice)),
        ),
    ]);
  },
);

// baseURL: from the iOS simulator, "http://127.0.0.1:8080" reaches the host.
let baseURL = "http://127.0.0.1:8080"

// Money is integer cents end to end; format only for display.
func formatCents(_ cents: Int) -> String {
    return String(format: "$%.2f", Double(cents) / 100.0)
}

struct Product: Codable, Identifiable {
    let id: Int; let name: String; let unitPrice: Int; let stock: Int
}

func fetchProducts() async throws -> [Product] {
    let (data, _) = try await URLSession.shared.data(from: URL(string: "\(baseURL)/products")!)
    return try JSONDecoder().decode([Product].self, from: data)
}

struct CatalogView: View {
    @State private var products: [Product] = []
    var body: some View {
        List(products) { p in
            HStack {
                VStack(alignment: .leading) { Text(p.name); Text(p.stock > 0 ? "In stock" : "Sold out").foregroundStyle(.secondary) }
                Spacer(); Text(formatCents(p.unitPrice))
            }
        }
        .task { products = (try? await fetchProducts()) ?? [] }
    }
}

gcloud sql instances create aurora-pg --database-version=POSTGRES_16 --tier=db-f1-micro --region=us-central1
gcloud run deploy aurora-api \
  --source . \
  --add-cloudsql-instances PROJECT:us-central1:aurora-pg \
  --set-env-vars DATABASE_URL="postgres://YOUR_DB_USER:YOUR_DB_PASSWORD@/aurora?host=/cloudsql/PROJECT:us-central1:aurora-pg" \
  --region us-central1 --allow-unauthenticated

# Spring path instead: drop the libpq DATABASE_URL and pass the JDBC SocketFactory env, e.g.
#   --set-env-vars JDBC_DATABASE_URL="jdbc:postgresql:///aurora?cloudSqlInstance=PROJECT:us-central1:aurora-pg&socketFactory=com.google.cloud.sql.postgres.SocketFactory",DB_USER=...,DB_PASSWORD=...

System: Extract the shopping ingredients from a recipe. Return ONLY JSON.
User: <the recipe text>

responseSchema (conceptual):
{ "type": "array", "items": {
    "type": "object",
    "properties": { "name": {"type":"string"}, "quantity": {"type":"string"} },
    "required": ["name"] } }

-- enable once: CREATE EXTENSION IF NOT EXISTS pg_trgm;
SELECT id, name, similarity(name, $1) AS score
FROM products
WHERE name % $1            -- trigram "is similar"
ORDER BY score DESC
LIMIT 3;

get_order_status(order_id: integer)    -> { status, placed_at, total }
check_stock(product_id: integer)       -> { name, stock }
estimate_restock(product_id: integer)  -> { eta_days }   # heuristic from history

# Each is a FunctionDeclaration:
{ "name": "get_order_status",
  "description": "Look up the current status of an order by its id.",
  "parameters": { "type": "object",
    "properties": { "order_id": { "type": "integer" } },
    "required": ["order_id"] } }

// support/agent.go (essentials) — google.golang.org/genai
client, _ := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GOOGLE_API_KEY"), // free AI Studio key, server-side only
	Backend: genai.BackendGeminiAPI,
})

tools := []*genai.Tool{{FunctionDeclarations: []*genai.FunctionDeclaration{{
	Name:        "get_order_status",
	Description: "Look up the current status of an order by its id.",
	Parameters: &genai.Schema{
		Type:       genai.TypeObject,
		Properties: map[string]*genai.Schema{"order_id": {Type: genai.TypeInteger}},
		Required:   []string{"order_id"},
	},
}}}} // ...plus check_stock and estimate_restock, declared the same way

cfg := &genai.GenerateContentConfig{Tools: tools}
resp, _ := client.Models.GenerateContent(ctx, model, contents, cfg) // contents = the user's question

for _, fc := range resp.FunctionCalls() { // the model chose a tool; we execute it
	result := dispatchReadOnly(ctx, pool, fc.Name, fc.Args)          // SELECT-only, against Postgres
	part := genai.NewPartFromFunctionResponse(fc.Name, result)
	_ = part // append the model's call turn + this function response to contents, then call again
	resp, _ = client.Models.GenerateContent(ctx, model, contents, cfg)
}
// resp now holds the grounded, natural-language answer

// SupportService.kt (essentials) — com.google.genai
val client = Client.builder().apiKey(System.getenv("GOOGLE_API_KEY")).build()

val tools = Tool.builder().functionDeclarations(
    FunctionDeclaration.builder()
        .name("get_order_status")
        .description("Look up the current status of an order by its id.")
        .parameters(orderIdSchema) // object { order_id: integer } — build with Schema.builder()
        .build(),
    // ...check_stock, estimate_restock declared the same way
).build()

val cfg = GenerateContentConfig.builder().tools(tools).build()
var resp = client.models.generateContent(model, question, cfg)

for (call in resp.functionCalls()) {                               // the model chose a tool
    val result = dispatchReadOnly(jdbc, call.name().get(), call.args().get()) // SELECT-only
    val fr = FunctionResponse.builder()
        .name(call.name().get())
        .response(mapOf("output" to result))
        .build()
    resp = client.models.generateContent(model, contentsWith(fr), cfg) // append fr, ask again
}
// resp.text() now holds the grounded answer

# Agent proposes (from POST /support) — NO mutation:
{ "action": "cancel", "orderId": 4821, "summary": "Cancel order 4821 (Aurora Tee ×2)", "requiresConfirmation": true }

# Human confirms -> the ONLY endpoint that mutates, idempotent like checkout:
POST /orders/{id}/cancel        Header: Idempotency-Key: <uuid>
Body:    { "action": "cancel", "orderId": 4821, "summary": "..." }   # the confirmed proposal
200:     { "orderId": 4821, "status": "cancelled" }   # replay returns the same result
404:     { "error": "not_found" }
409:     { "error": "not_cancellable" }               # e.g. already shipped

{"time":"...","level":"INFO","msg":"checkout.stock_decremented","trace_id":"a1b2","product_id":7,"qty":2}
{"time":"...","level":"INFO","msg":"checkout.total_computed","trace_id":"a1b2","total_cents":5998}
{"time":"...","level":"INFO","msg":"checkout.order_inserted","trace_id":"a1b2","order_id":4821}
{"time":"...","level":"INFO","msg":"checkout.committed","trace_id":"a1b2","order_id":4821}

// logging setup
logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo}))
slog.SetDefault(logger)

// trace-id middleware
type ctxKey struct{}
func withTrace(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		ctx := context.WithValue(r.Context(), ctxKey{}, uuid.NewString())
		next.ServeHTTP(w, r.WithContext(ctx))
	})
}

// inside Checkout, log each phase with the request's trace id:
tid, _ := ctx.Value(ctxKey{}).(string)
log := slog.With("trace_id", tid)
log.InfoContext(ctx, "checkout.stock_decremented", "product_id", l.ProductID, "qty", l.Qty)
// ...total_computed, order_inserted, committed / rolled_back, out_of_stock, idempotency_hit

// application.properties:
//   logging.structured.format.console=ecs

@Component
class TraceIdFilter : OncePerRequestFilter() {
    override fun doFilterInternal(req: HttpServletRequest, res: HttpServletResponse, chain: FilterChain) {
        MDC.put("traceId", UUID.randomUUID().toString())
        try { chain.doFilter(req, res) } finally { MDC.clear() }
    }
}

// inside the @Transactional checkout — MDC traceId rides along on every line:
private val log = LoggerFactory.getLogger(CheckoutService::class.java)
log.info("checkout.stock_decremented product_id={} qty={}", l.productId, l.qty)
// ...total_computed, order_inserted, committed / rolled_back (on OutOfStockException), idempotency_hit