Warm cache

Layer exposes two warm surfaces. hint_cache_warm is the Turbopuffer-compatible hint; warm is the Layer-only shortcut that creates a gateway warm job.

Hint-cache warm

GET /v1/namespaces/products/hint_cache_warm

Layer-side steps (all default-on):

Step	What it does
turbopuffer=true	Forwards the warm hint upstream.
documents=true	Starts an origin warm job to backfill the NVMe cache.
snapshots=true	Mirrors the latest S3 snapshot body into NVMe.

Disable steps independently:

GET /v1/namespaces/products/hint_cache_warm?turbopuffer=false&documents=false&snapshots=true

The response reports per-step status. If documents is enabled, the response includes a warm job; poll it through /warm-jobs/{id}.

Layer warm

POST /v2/namespaces/{ns}/warm creates an asynchronous job that pages through Turbopuffer, backfills Aerospike, and refreshes cache_warmed_through. Use it when bootstrapping a namespace whose data was written outside the gateway.

POST /v2/namespaces/products/warm?page_size=1000

The response is 202 Accepted with the warm job:

{
  "id": "warm-job-uuid",
  "namespace": "products",
  "status": "running",
  "progress": 0,
  "documents_scanned": 0,
  "created_at": "2026-05-26T10:00:00Z"
}

Poll it through:

GET /v2/namespaces/products/warm-jobs/warm-job-uuid

Cache-cold behavior

The split is deliberate. Fetch is correctness-first: a cache outage must not turn into a missing document. Warm is throughput-first: warming on a cold cache would be wasted work, so the gateway surfaces the cold state to the caller rather than silently no-op-ing.