Tier pgvector columns to Iceberg and narrow vector searches to their nearest clusters

CLAUDE.md

@@ -54,7 +54,7 @@
   - Release tags use 3-part SemVer (`vMAJOR.MINOR.PATCH`, e.g. `v1.0.0`). This is required, not stylistic: ColdFront is a Go module (`github.com/pgedge/coldfront`), and the toolchain only treats full `vX.Y.Z` tags as releases — a 2-part `v1.0` tag yields pseudo-versions. Git tags, GitHub releases, container image tags, and the changelog all use this form. The patch field keeps a bugfix-only release (`v1.0.1`) distinct from a feature release (`v1.1.0`).
   - The PostgreSQL extension keeps the conventional 2-part version in `extension/coldfront/coldfront.control` (`default_version`) and the `coldfront--X.Y.sql` / `coldfront--X.Y--X.Z.sql` upgrade-script filenames, per PG convention. Extension `1.0` ships inside release `v1.0.0`; a patch release may carry the same extension version or bump it with an upgrade script when the SQL changes.
 - Build 4 static binaries per release: linux-amd64, linux-arm64, darwin-amd64, darwin-arm64
-- Build command: `CGO_ENABLED=0 go build -ldflags="-s -w"`
+- Build command: `CGO_ENABLED=0 go build -ldflags="-s -w -X github.com/pgedge/coldfront/internal/version.Version=$TAG -X github.com/pgedge/coldfront/internal/version.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)"` (the compactor stamps `-X main.Version` / `-X main.BuildTime`); `make build` derives the stamp from `git describe`
 - Release notes format: `## Added` / `## Changed` / `## Fixed`
   - Only list user-facing changes — no internal test additions, no same-cycle fix churn
   - `## Fixed` is for bugs that existed in the previous release, not things broken and fixed in the same cycle

Makefile

@@ -3,10 +3,12 @@
 # golangci-lint path: PATH first, else the default go install location. ci/matrix.sh
 # passes GOLANGCI=<resolved path> so the compactor gate uses the same linter.
 GOLANGCI ?= $(shell command -v golangci-lint 2>/dev/null || echo $(HOME)/go/bin/golangci-lint)
+VERSION    ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo unknown)
+BUILD_TIME := $(shell date -u +"%Y-%m-%dT%H:%M:%SZ")
 
 build:
-	CGO_ENABLED=0 go build -ldflags="-s -w" -o bin/archiver ./cmd/archiver
-	CGO_ENABLED=0 go build -ldflags="-s -w" -o bin/partitioner ./cmd/partitioner
+	CGO_ENABLED=0 go build -ldflags="-s -w -X github.com/pgedge/coldfront/internal/version.Version=$(VERSION) -X github.com/pgedge/coldfront/internal/version.BuildTime=$(BUILD_TIME)" -o bin/archiver ./cmd/archiver
+	CGO_ENABLED=0 go build -ldflags="-s -w -X github.com/pgedge/coldfront/internal/version.Version=$(VERSION) -X github.com/pgedge/coldfront/internal/version.BuildTime=$(BUILD_TIME)" -o bin/partitioner ./cmd/partitioner
 
 # compactor: a SEPARATE Go module (cmd/compactor/go.mod) so iceberg-go's heavy
 # dependency tree never links into the lean archiver. Its full gate — vet, lint,
@@ -18,7 +20,7 @@ compactor:
 	cd cmd/compactor && go vet ./...
 	cd cmd/compactor && "$(GOLANGCI)" run --timeout=5m
 	cd cmd/compactor && go test ./...
-	cd cmd/compactor && CGO_ENABLED=0 go build -ldflags="-s -w" -o $(CURDIR)/bin/compactor .
+	cd cmd/compactor && CGO_ENABLED=0 go build -ldflags="-s -w -X main.Version=$(VERSION) -X main.BuildTime=$(BUILD_TIME)" -o $(CURDIR)/bin/compactor .
 
 test:
 	go test -race -v ./...

README.md

@@ -121,13 +121,15 @@ The following table lists the ColdFront guides and what each one covers:
 
 | Doc | Contents |
 |---|---|
+| **[Embeddings](docs/usage_vectors.md)** | Storing and searching embeddings with the pgvector interface |
 | **[Usage](docs/usage.md)** | Day-to-day use - both modes plus the standalone partition manager, one-time setup, reading/writing, supported types, the partition CLI, storage backends, distributed (mesh) setup, tuning |
 | **[Installation](docs/installation.md)** | Build from source (Docker or bare-metal); Testing & CI |
 | **[Object store setup](docs/object_store.md)** | Get ColdFront running on cloud S3 (virtual-hosted), end-to-end |
 | **[Compaction](docs/compaction.md)** | Cold-tier table maintenance - compaction, snapshot expiry, orphan-file removal |
 | **[Architecture](docs/architecture.md)** | Shared architecture and core mechanics |
 | **[Architecture: tiered](docs/architecture_tiered.md)** | Tiered (hot PG + cold Iceberg) deep dive |
 | **[Architecture: decoupled](docs/architecture_decoupled.md)** | Decoupled (iceberg-only) deep dive |
+| **[Architecture: vectors](docs/architecture_vectors.md)** | Vector storage internals - type mapping, routing state, cluster assignment, layout |
 
 ## Least-privilege application roles
 
@@ -180,7 +182,7 @@ pgedge-coldfront/
 │   ├── partcfg/                ← in-DB, Spock-replicated per-table lifecycle config
 │   ├── partition/              ← partition create/find/detach/drop (time + id modes)
 │   ├── sqlutil/                ← shared SQL helpers
-│   ├── view/                   ← unified view + trigger generation
+│   ├── view/                   ← unified view generation
 │   └── watermark/              ← archive_watermark table CRUD
 ├── extension/coldfront/        ← PGXS C extension (DML hooks, bakery, registry, SQL)
 ├── ci/
@@ -201,7 +203,8 @@ pgedge-coldfront/
 │   └── seaweedfs-s3.json        ← SeaweedFS S3 auth config (example)
 ├── docs/                       ← MkDocs site (user docs; mkdocs.yml at repo root)
 │   ├── index.md · installation.md · object_store.md · usage.md · compaction.md
-│   ├── architecture.md · architecture_tiered.md · architecture_decoupled.md · changelog.md
+│   ├── architecture.md · architecture_tiered.md · architecture_decoupled.md
+│   ├── architecture_vectors.md · usage_vectors.md · changelog.md
 │   └── formal/                 ← TLA+ model of the bakery protocol (Bakery_v2.tla)
 ├── docker-compose.yml          ← END-USER single-node stack (ports published)
 ├── docker-compose.matrix.yml   ← CI only: single-node vanilla matrix