# hev layer

> Retrieval gateway and transform runtime around Turbopuffer.

hev layer is a transparent proxy in front of Turbopuffer that adds operational semantics — document cache, namespace snapshots, search history, pipeline state — plus a Kubernetes-native UDF transform runtime for embedding, classification, tagging, and attribute migration.

These docs are queryable from the command line — better than reading this file: install `ask` (`go install github.com/hev/ask/cmd/ask@latest`), then `ask --endpoint https://hevlayer.com/api/ask search "<question>"` for ranked sections with deep links, `section get "<id>"` for detail, `overview` for the full map. Setup and verbs: https://hevlayer.com/docs/agents

The full concatenated docs are at https://hevlayer.com/llms-full.txt.

## Overview
- [Introduction](https://hevlayer.com/docs): Layer is a gateway and function runtime for modern retrieval systems. It scales compute for multi-stage indexing pipelines and runs functions across every row of your index, with all durable state in object storage.
- [Concepts](https://hevlayer.com/docs/concepts): How the gateway composes Turbopuffer, NVMe cache, PostgreSQL, S3, and metrics — and the core nouns you'll work with.
- [Document model](https://hevlayer.com/docs/document-model): A Layer document and the reserved attributes the gateway manages on every Turbopuffer row.
- [No Guarantees](https://hevlayer.com/docs/guarantees): Layer can't offer guarantees — here's what we commit to instead.
- [Tradeoffs](https://hevlayer.com/docs/tradeoffs): The current product posture and the cases it is not trying to cover.
- [Limits](https://hevlayer.com/docs/limits): Current ceilings inherited from the components we ship with, and what we don't cap.
- [Agents](https://hevlayer.com/docs/agents): Use the Layer docs and layer CLI from your coding agent with one-file skills that work across agent harnesses.
- [Roadmap & Changelog](https://hevlayer.com/docs/roadmap): Where hev layer is headed next, and what has shipped.
- [FAQ](https://hevlayer.com/docs/faq): Licensing, pricing, open source plans, and how to get started.

## Operations
- [Install](https://hevlayer.com/docs/install): How to bring up a hev layer environment: AWS resources via Terraform, runtime via Helm.
- [Operator Overview](https://hevlayer.com/docs/kubernetes/operator): What layer-operator reconciles and how it relates to the gateway.
- [VectorStore CRD](https://hevlayer.com/docs/kubernetes/vectorstore-crd): Backend connection and gateway inbound auth policy for a Layer install.
- [ApiKey CRD](https://hevlayer.com/docs/kubernetes/apikey-crd): Minted API keys as Kubernetes resources: lifecycle, entitlements, and opaque claims.
- [Warehouse CRD](https://hevlayer.com/docs/kubernetes/warehouse-crd): Declared upstream data source: identity, credential, and verified reachability.
- [Index CRD](https://hevlayer.com/docs/kubernetes/index-crd): Declarative representation of a namespace managed by Layer.
- [InfraRules CRD](https://hevlayer.com/docs/kubernetes/scaling-crd): Cluster-wide compute pools, document cache rules, and workload scaling.
- [Pipeline CRD](https://hevlayer.com/docs/kubernetes/pipeline-crd): Staged row-changing work declared as a Kubernetes resource.
- [Function CRD](https://hevlayer.com/docs/kubernetes/function-crd): Stateless user-defined functions declared as Kubernetes resources.
- [Failure Modes](https://hevlayer.com/docs/failure-modes): How reads and writes degrade when the gateway, cache, or pipeline runs into trouble.
- [Layer CLI](https://hevlayer.com/docs/cli): The layer CLI manages environments, observes indexes, pipelines, and UDFs, mints API keys, and runs Function manifests.
- [Dashboard](https://hevlayer.com/docs/dashboard): Running the in-cluster operations dashboard: the access it needs, networking, auth, and turning it off.

## API
- [Introduction](https://hevlayer.com/docs/api/introduction): What Layer adds on top of the Turbopuffer wire contract, and how to point a client at the gateway.
- [Write & Stage](https://hevlayer.com/docs/api/write): Write rows to a namespace and stage documents in the cache.
- [Query & Fetch](https://hevlayer.com/docs/api/query): Vector similarity search with stable reads, query by id, and cached document fetch.
- [Scan](https://hevlayer.com/docs/api/scans): On-demand row selection by filter, full-text, or radius — IDs, count, or values.
- [Pipelines](https://hevlayer.com/docs/api/pipelines): Organize a two-stage indexing pipeline: extract + chunk on CPU, embed on GPU, trigger runs and wait for completion.
- [Namespace metadata](https://hevlayer.com/docs/api/namespace-metadata): Read namespace metadata enriched with Layer freshness signals.
- [Warm cache](https://hevlayer.com/docs/api/warm-cache): Warm a namespace's NVMe cache and snapshot mirror.
- [Snapshot History](https://hevlayer.com/docs/api/snapshots): Facet snapshot jobs, history, bodies, and activity streams.
- [Query History](https://hevlayer.com/docs/api/search-history): Per-namespace query and clickstream history backed by JSONL in S3.

## Search knowledge graph

Version: 2
Generated: 2026-06-14T22:41:19.143Z
Content hash: 06c39943e6e6466069dcce5f660b09f2fffd305244ecf9447f9a6c39afc73b42

Context:
## Layer (hev layer)

Layer is a **gateway and function runtime for retrieval systems**: a Rust proxy (the *gateway*) that fronts **Turbopuffer**, plus a Kubernetes *operator*, both running in your own cluster. The gateway is wire-compatible with the Turbopuffer client API — existing clients keep working when pointed at it — and Layer documents only what it *adds* on top of upstream routes, exposing Layer-only features under `/v2/`.

### Core building blocks
- **Gateway** — transparent Turbopuffer proxy adding fetch, query by id, scans, result count, facet snapshots, a document cache (pull-through reads), write-path stamping, stable reads, query/clickstream history, warm jobs, pipelines, and a UDF runtime.
- **Operator** — reconciles four CRDs (`Index`, `InfraRules`, `Pipeline`, `Function`). Decoupled from the gateway, which only ever *reads* CRD status.
- **Backing services** (all open source): **Aerospike** (NVMe document cache, ephemeral), **PostgreSQL** (pipeline/indexing-state queue only), **VictoriaMetrics** (metrics), **Karpenter** (node autoscaling), **KEDA** (pod autoscaling to zero). Durable state lives only in **S3** — Layer processes are stateless and elastic.

### Key concepts users ask about
- **Stable reads / stable watermark** — a background watcher records an epoch-ms watermark when a namespace's Turbopuffer index status is up-to-date; while updating, queries filter to fully-indexed rows so reads never see partial writes. Surfaced via `stable_as_of`; configured per Index CRD via `consistency`.
- **Reserved `hevlayer` attributes** — server-stamped write watermark, shard key, and Function completion/invalidation markers; users must not write `_hevlayer_*` attributes.
- **Document cache** — pull-through reads: Aerospike checked first; misses fall through to Turbopuffer/S3 and backfill. Cache failures are soft (never block reads); upstream failures are hard. Hit/miss reported per response.
- **Snapshots & facets** — content-addressed S3 facet histograms written when a namespace is stable.
- **Scans** — on-demand row selection by filter, full-text (`fts`), or radius (`ann`), returning IDs or counts. Origin scans use `threads` / `spec.scan.threads` to cap concurrent upstream shard fan-out.
- **Pipelines vs Functions/UDFs** — pipelines ingest external data into rows; Functions run over rows that already exist. Workers own writes and can patch attributes, fan out with deterministic IDs, or re-upsert rows. Both scale via KEDA off queue depth, pinned to compute pools in `InfraRules`.
- **Dashboard** — read-mostly operator GUI reading the same gateway API.

### How users talk about it
Users say "the gateway," "drop-in Turbopuffer client," "warm the cache," "stable read," "strongly consistent query," "snapshot," "facet counts," "scan a filter," "stage/claim/embed," "UDF/function," "compute pool," and "scale to zero." Install is two-stage: **Terraform** (AWS resources) then **Helm** (gateway/operator/cache).

Glossary: