A design spec your agents can build from and your team can actually review.

# Task: implement S6 of `online-shop`

You are implementing part of the system described in `online-shop.spec.yaml`. That spec is the source of truth:
do not change contracts, tables or connections in code. If the spec looks wrong or incomplete, stop and
propose a change to the spec instead of working around it.

**Component(s) you are changing:** storefront

## Steps to implement

```yaml
- id: S6
  via: storefront_to_order-processing-api
  call: orders.CreateOrder
  description: Stores the order and queues it for fulfilment, in one transaction.
  errors:
    ALREADY_EXISTS: returns the order already stored for that idempotency key
  request:
    build: CreateOrderRequest
    map:
      customerId: request.customerId
      idempotencyKey: headers.Idempotency-Key
      itemCount: cart.item_count
      totalCents: cart.total_cents
```

## Surrounding steps (context only; already implemented elsewhere)

```yaml
- id: S4
  via: customer_to_storefront
  call: POST /checkout
  description: Turns the saved cart into an order. Safe to retry with the same Idempotency-Key.
  headers:
    Idempotency-Key: required
  request: CheckoutRequest
  errors:
    "401": missing or expired token
    "404": no saved cart with that id
    "409": the Idempotency-Key was used for a different cart
- id: S5
  via: storefront_to_carts_db
  transaction:
    - select: carts_db.carts
      as: cart
      where: id = request.cartId
- id: S7
  via: order-processing-api_to_orders_db
  transaction:
    - insert: orders_db.orders
      as: order
      map:
        id: $uuid
        customer_id: request.customerId
        status: "'PLACED'"
        item_count: request.itemCount
        total_cents: request.totalCents
        idempotency_key: request.idempotencyKey
      on_conflict:
        idempotency_key: return the existing order
    - insert: orders_db.outbox
      as: outbox
      map:
        id: $uuid
        aggregate_id: order.id
        event_type: "'order.placed'"
        payload:
          build: OrderPlacedEvent
          map:
            eventId: outbox.id
            eventType: "'order.placed'"
            schemaVersion: "1"
            orderId: order.id
            customerId: order.customer_id
            itemCount: order.item_count
- id: S8
  via: storefront_to_order-processing-api
  respond:
    status: 200
    body:
      build: CreateOrderResponse
      map:
        orderId: order.id
        status: order.status
- id: S9
  via: customer_to_storefront
  respond:
    status: 201
    body: CreateOrderResponse
```

## Connections

```yaml
storefront_to_order-processing-api:
  from: storefront
  to: order-processing-api
  type: internal-grpc
  auth: mtls-identity
  timeout: 2s
  deadlinePropagation: true
  carries:
    - CreateOrderRequest
    - CreateOrderResponse
customer_to_storefront:
  from: customer
  to: storefront
  type: https-rest
  auth: oauth2-jwt
  boundary: internet->dmz
  edgeProtection: WAF managed rules, 20 req/s per customer
  timeout: 5s
  retryPolicy: client retries with the same Idempotency-Key
  carries:
    - CartUpdate
    - CartSaved
    - CheckoutRequest
    - CreateOrderResponse
storefront_to_carts_db:
  from: storefront
  to: carts_db
  type: redis
  auth: auth-token
  timeout: 50ms
order-processing-api_to_orders_db:
  from: order-processing-api
  to: orders_db
  type: postgres
  auth: iam-db-auth
  statementTimeout: 2s
  connectionPool: 20
```

Connection types (platform standards):

```yaml
https-rest:
  mode: sync
  protocol: HTTPS
  port: 443
  encryption:
    inTransit: TLS1.2+
  auth:
    - oauth2-jwt
    - api-key
  requires:
    - timeout
    - retryPolicy
internal-grpc:
  mode: sync
  protocol: gRPC
  port: 443
  encryption:
    inTransit: TLS1.3
    mTLS: true
  auth:
    - mtls-identity
  requires:
    - timeout
    - deadlinePropagation
postgres:
  mode: sync
  protocol: PostgreSQL
  port: 5432
  encryption:
    inTransit: TLS1.2+
    atRest: KMS
  auth:
    - iam-db-auth
    - secrets-manager
  requires:
    - statementTimeout
    - connectionPool
redis:
  mode: sync
  protocol: Redis
  port: 6379
  encryption:
    inTransit: TLS1.2+
    atRest: KMS
  auth:
    - iam-auth
    - auth-token
  requires:
    - timeout
```

## Payload types

```yaml
CreateOrderRequest:
  description: Order built from the cart
  fields:
    customerId:
      type: uuid
      pii: true
    idempotencyKey:
      type: string
    itemCount:
      type: int
      min: 1
    totalCents:
      type: int
      min: 0
CreateOrderResponse:
  description: Order id and status
  fields:
    orderId:
      type: uuid
      description: Use it to track the order
    status:
      type: string
      enum:
        - PLACED
CartUpdate:
  description: What is in the customer's cart
  fields:
    cartId:
      type: uuid
      description: Chosen by the browser when the cart is first saved
    customerId:
      type: uuid
      pii: true
      description: The signed-in customer
    itemCount:
      type: int
      min: 0
      description: Number of items; 0 empties the cart
    totalCents:
      type: int
      min: 0
      description: Cart total in cents
      tax included: null
CartSaved:
  description: The saved cart's id
  fields:
    cartId:
      type: uuid
CheckoutRequest:
  description: The cart the customer is checking out
  fields:
    cartId:
      type: uuid
      description: The cart saved with PUT /cart
    customerId:
      type: uuid
      pii: true
      description: Must match the token's subject
OrderPlacedEvent:
  description: Placed order, for fulfilment
  classification: confidential
  fields:
    eventId:
      type: uuid
    eventType:
      type: string
      const: order.placed
    schemaVersion:
      type: int
      const: 1
    orderId:
      type: uuid
    customerId:
      type: uuid
      pii: true
    itemCount:
      type: int
```

## Tables

```yaml
carts_db.carts:
  description: Open carts, kept for 7 days
  columns:
    id:
      type: uuid
      pk: true
    customer_id:
      type: uuid
      pii: true
    item_count:
      type: int
    total_cents:
      type: bigint
orders_db.orders:
  description: Orders
  columns:
    id:
      type: uuid
      pk: true
    customer_id:
      type: uuid
      pii: true
    status:
      type: text
      enum:
        - PLACED
        - CANCELLED
    item_count:
      type: int
    total_cents:
      type: bigint
    idempotency_key:
      type: text
      unique: true
    created_at:
      type: timestamptz
      default: now()
orders_db.outbox:
  description: Events waiting to be published
  columns:
    id:
      type: uuid
      pk: true
    aggregate_id:
      type: uuid
    event_type:
      type: text
    payload:
      type: jsonb
      schema: OrderPlacedEvent
    created_at:
      type: timestamptz
      default: now()
    published_at:
      type: timestamptz
      nullable: true
```

## Invariants that must hold

- one checkout creates at most one order, even when the customer retries
- every orders row has exactly one outbox row (written in the same transaction)
- at most one shipment per order_id, even with duplicate SQS delivery

## Policies that apply

- **P2**: Connections crossing a trust boundary must authenticate
- **P5**: A flow step's payload must be listed in its connection's `carries`
- **P6**: Downstream sync timeouts must fit within the entry point's timeout
- **TYP002**: Mapping sources must be existing fields of the payload in scope
- **TYP003**: Mapped source and target types must be compatible

## Acceptance scenarios (write one test per scenario)

- [ ] **happy path**: when the customer checks out a cart with 2 items → 201 with orderId; 1 orders row; 1 outbox row then published_at set; 1 PENDING shipment with item_count 2
- [ ] **customer retries checkout**: when the same checkout is sent twice with the same Idempotency-Key → same orderId returned both times; 1 orders row; 1 outbox row

## Definition of done

- Every mapping is implemented exactly as specified (field names, types, enum values, on_conflict behaviour).
- Each acceptance scenario has an automated test. Use real dependencies in containers (e.g. Testcontainers for Postgres, LocalStack for SQS); don't mock the database or queue.
- The error-handling paths in the steps (`on_error`, `on_conflict`, `on_unknown_schema_version`) are tested.
- `archspec check online-shop.spec.yaml` still passes with no new errors.

-- Generated by archspec from online-shop.spec.yaml. Do not edit; change the spec instead.

CREATE SCHEMA IF NOT EXISTS carts_db;
CREATE SCHEMA IF NOT EXISTS fulfillment_db;
CREATE SCHEMA IF NOT EXISTS orders_db;

CREATE TABLE carts_db.carts (
  id UUID PRIMARY KEY,
  customer_id UUID NOT NULL,
  item_count INT NOT NULL,
  total_cents BIGINT NOT NULL
);
COMMENT ON COLUMN carts_db.carts.customer_id IS 'PII';

CREATE TABLE orders_db.orders (
  id UUID PRIMARY KEY,
  customer_id UUID NOT NULL,
  status TEXT NOT NULL CHECK (status IN ('PLACED', 'CANCELLED')),
  item_count INT NOT NULL,
  total_cents BIGINT NOT NULL,
  idempotency_key TEXT NOT NULL UNIQUE,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
COMMENT ON COLUMN orders_db.orders.customer_id IS 'PII';

CREATE TABLE orders_db.outbox (
  id UUID PRIMARY KEY,
  aggregate_id UUID NOT NULL,
  event_type TEXT NOT NULL,
  payload JSONB NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  published_at TIMESTAMPTZ
);
COMMENT ON COLUMN orders_db.outbox.payload IS 'schema: OrderPlacedEvent';

CREATE TABLE fulfillment_db.shipments (
  id UUID PRIMARY KEY,
  order_id UUID NOT NULL UNIQUE,
  customer_id UUID NOT NULL,
  item_count INT NOT NULL,
  status TEXT NOT NULL CHECK (status IN ('PENDING', 'SHIPPED')),
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
COMMENT ON COLUMN fulfillment_db.shipments.customer_id IS 'PII';

CREATE TABLE fulfillment_db.processed_events (
  event_id UUID PRIMARY KEY,
  processed_at TIMESTAMPTZ NOT NULL DEFAULT now()
);