Makefile

# mcp-data-platform Makefile

# Variables
BINARY_NAME := mcp-data-platform
VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
BUILD_TIME := $(shell date -u '+%Y-%m-%d_%H:%M:%S')
GO_VERSION := $(shell go version | cut -d ' ' -f 3)
LDFLAGS := -ldflags "-X github.com/txn2/mcp-data-platform/internal/buildinfo.Version=$(VERSION)"

# Directories
CMD_DIR := ./cmd/mcp-data-platform
BUILD_DIR := ./build
DIST_DIR := ./_dist
UI_DIR := ./ui
UI_EMBED_DIR := ./internal/ui/dist
CV_EMBED_DIR := ./internal/contentviewer/dist

# Tool versions — keep in sync with .github/workflows/ci.yml
GOLANGCI_LINT_VERSION := v2.14.0
# gosec is pinned to a commit on master: v2.29.0, the latest release, cannot
# load packages built by Go 1.27.2 (securego/gosec#1771, export data version 5).
GOSEC_VERSION := v2.29.1-0.20261015133444-707f2271f665
GREMLINS_VERSION := v0.6.0
# govulncheck is pinned for the same reason the others are: its report is judged
# by scripts/govulncheck-gate.py, which reads the -format json message stream, so
# local and CI must run the same scanner against the same schema. .github/workflows/ci.yml
# installs this version.
GOVULNCHECK_VERSION := v1.9.0
# osv-scanner reads the GitHub advisory database, which carries advisories the
# Go vulnerability database govulncheck reads does not (the 15 excelize
# advisories of #2143 were in one and not the other), and it reads the UI's npm
# lockfile, which nothing else scans. .github/workflows/ci.yml installs this version.
OSV_SCANNER_VERSION := v2.5.1

# Total-coverage floor. This is the single source of truth for the project
# coverage gate: .github/workflows/ci.yml, codecov.yml (project target) and
# CONTRIBUTING.md must all state this same figure, and TestGateFiguresAgree
# (test/structure/pins_test.go) fails when they drift apart. Patch coverage (changed lines)
# is a separate gate at PATCH_COVERAGE_MIN.
COVERAGE_MIN := 82
PATCH_COVERAGE_MIN := 80

# Where `make security` parks the govulncheck JSON report the gate judges. It
# is a build artifact, removed by the target that writes it.
GOVULN_REPORT := build/govulncheck-report.json

# Go commands
GO := go
GOTEST := $(GO) test
GOBUILD := $(GO) build
GOMOD := $(GO) mod
GOVET := $(GO) vet
GOFMT := gofmt
GOLINT := golangci-lint

.PHONY: all migrate-check-diff build test lint lint-full fmt clean install help docs-serve docs-build docs-images-check verify verify-release alert-rules-test builtin-pages-check \
	tools-check dead-code mutate patch-coverage patch-coverage-check coverage-summary doc-check acceptance acceptance-release acceptance-check acceptance-release-check release-tag-check schedule-lane schedule-lane-ui realdb-lane state-readers-check e2e-copy-check route-manifest-check posture-check preverify preverify-fast swagger swagger-check verify-checks verify-go verify-static verify-docker verify-ui verify-static-ui vet-tags \
	semgrep semgrep-diff semgrep-changed codeql sast osv embed-clean migrate-check \
	frontend-install frontend-build frontend-build-content-viewer content-viewer-embed \
	frontend-dev frontend-mock frontend-test frontend-lint frontend-e2e \
	frontend-e2e-public-viewer \
	e2e-up e2e-down e2e-seed e2e-test e2e e2e-logs e2e-clean \
	dev dev-info dev-up dev-stop dev-down dev-kill-hosts mock-check \
	preview-apps preview-platform-info

## all: Build and test
all: build test lint

## build: Build the binary
build: swagger
	@echo "Building $(BINARY_NAME)..."
	@mkdir -p $(BUILD_DIR)
	$(GOBUILD) $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME) $(CMD_DIR)
	@echo "Binary built: $(BUILD_DIR)/$(BINARY_NAME)"

## test: Run tests
test:
	@echo "Running tests..."
	@# -p 6 bounds how many packages are built and run at once.
	@#
	@# The default is one per core, which on an 18-core machine means this
	@# target alone tries to own the whole machine — and inside `verify` it is
	@# one of four lanes doing that. Measured there: this lane finished 93s
	@# before the slowest one, so its unbounded appetite bought slack it did
	@# not need while inflating the lane that actually sets the wall clock
	@# (the e2e suite ran 109s alone and ~235s beside it). Spending some of
	@# that slack to stop starving the pole is the trade.
	@#
	@# -race multiplies the memory and CPU each package costs, which is why
	@# the bound matters more here than on an ordinary test run.
	$(GOTEST) -v -race -p 6 -coverprofile=coverage.out ./...
	@echo "Tests complete."

## test-short: Run tests without race detection (faster)
test-short:
	@echo "Running tests (short)..."
	$(GOTEST) -v ./...

## test-integration: Run integration tests
test-integration:
	@echo "Running integration tests..."
	$(GOTEST) -v -tags=integration ./...

# Real-DB round-trip gate for tool write paths. Runs every integration test
# named *RealDB* against a self-provisioned pgvector container (testcontainers),
# exercising the actual schema (NOT NULL constraints, defaults, column types)
# that sqlmock cannot. This is the gate that would have caught the prompt-create
# defect that shipped to production (pq.Array(nil) -> NULL into NOT NULL tags).
# Convention: name any tool write-path round-trip test *RealDB* so it runs here.
# Requires Docker. Part of `verify`, alongside migrate-check.
## test-realdb: Real-Postgres round-trip gate for store write paths
test-realdb:
	@echo "Running real-DB round-trip gate..."
	@# One Postgres for the whole gate, not one per test.
	@#
	@# internal/testdb.New is called at 163 sites and per test, not per
	@# package. A container plus a full replay of the migration set for each
	@# of them cost ~420s here and made this the slowest lane in `verify` by
	@# roughly eight times. Instead: start one server, apply the migrations
	@# once into a template database, and let each test clone it with
	@# CREATE DATABASE ... TEMPLATE, which Postgres does as a file copy.
	@#
	@# Isolation is unchanged. Every test still gets a private database that
	@# nothing else writes to; what is shared is one postgres process. The
	@# harness falls back to a container per test when TESTDB_DSN is unset,
	@# so a bare `go test -tags=integration ./...` still works.
	@#
	@# -p 4 still bounds package concurrency: it is what keeps 34 packages
	@# from opening pools faster than one server will accept them.
	@# The sampler reports the peak connections the run held, in total and for
	@# the packages that held the most, beside REALDB_MAX_CONNECTIONS (#2249).
	@set -e; \
	report=$$(mktemp); sampler=; \
	finish() { \
		if [ -n "$$sampler" ]; then kill -TERM $$sampler 2>/dev/null; wait $$sampler 2>/dev/null || true; cat "$$report"; fi; \
		rm -f "$$report"; \
		docker rm -f $(REALDB_PG_CONTAINER) >/dev/null 2>&1 || true; \
	}; \
	trap finish EXIT; \
	docker rm -f $(REALDB_PG_CONTAINER) >/dev/null 2>&1 || true; \
	docker run -d --name $(REALDB_PG_CONTAINER) \
		-e POSTGRES_USER=test -e POSTGRES_PASSWORD=test -e POSTGRES_DB=postgres \
		-p 127.0.0.1::5432 $(REALDB_PG_IMAGE) \
		-c max_connections=$(REALDB_MAX_CONNECTIONS) -c fsync=off -c full_page_writes=off \
		-c synchronous_commit=off >/dev/null; \
	pg_port=$$(docker port $(REALDB_PG_CONTAINER) 5432/tcp | head -1 | sed 's/.*://'); \
	if [ -z "$$pg_port" ]; then echo "FAIL: could not read the published Postgres port" >&2; exit 1; fi; \
	echo "  waiting for Postgres on :$$pg_port..."; \
	for i in $$(seq 1 60); do \
		docker exec $(REALDB_PG_CONTAINER) pg_isready -h localhost -p 5432 -U test >/dev/null 2>&1 && break; \
		if [ "$$i" = "60" ]; then echo "FAIL: Postgres did not become ready" >&2; exit 1; fi; \
		sleep 1; \
	done; \
	echo "  building the migrated template once..."; \
	docker exec $(REALDB_PG_CONTAINER) psql -U test -d postgres -q \
		-c 'CREATE DATABASE $(REALDB_TEMPLATE)'; \
	MIGRATE_TEST_DSN="postgres://test:test@localhost:$$pg_port/$(REALDB_TEMPLATE)?sslmode=disable" \
		$(GOTEST) -count=1 -run TestMigrationsAgainstRealPostgres ./pkg/database/migrate/ >/dev/null; \
	python3 scripts/realdb-connections.py $(REALDB_PG_CONTAINER) "$$report" & sampler=$$!; \
	TESTDB_DSN="postgres://test:test@localhost:$$pg_port/postgres?sslmode=disable" \
	TESTDB_TEMPLATE="$(REALDB_TEMPLATE)" \
		$(GOTEST) -count=1 -p 4 -tags=integration -run '$(REALDB_RUN)' $(REALDB_PKGS)
	@echo "Real-DB gate passed."

# Live post-deploy smoke: connects to a RUNNING MCP server as a real MCP client
# (admin API key) and exercises every user-facing write tool end to end, then
# cleans up. This is the layer that catches deployment drift / config the
# in-process gates cannot see. Skips unless MCP_API_KEY is set.
## smoke: Live smoke against a running MCP (env: MCP_BASE_URL, MCP_API_KEY)
smoke:
	@echo "Running live smoke against $${MCP_BASE_URL:-http://localhost:8099}..."
	$(GOTEST) -count=1 -tags=integration ./test/smoke/ -run Smoke -v

# Real-Postgres migration gate. Applies every embedded migration + the dev seed
# to a disposable pgvector instance (up -> seed -> down -> up), catching SQL the
# planner only rejects against a live engine (e.g. a non-IMMUTABLE function in an
# index expression), down-migration dependency-order bugs, and dev-seed rot.
# sqlmock and the embedded-file presence checks cannot catch these. Provisions
# its own container on its own port so it never touches the dev DB.
# Run against every PostgreSQL major a deployment may be on, because the engine
# is what decides whether this SQL is legal and the majors disagree. PostgreSQL
# 17 restricts search_path to pg_catalog and pg_temp during maintenance
# operations, so an index expression whose function body calls a function of
# ours builds on 16 and fails on 17. A single-major gate reported that as green
# and it reached a release (000102, fixed in 000111). One major is not a gate.
# Real-DB gate: one shared Postgres. fsync/full_page_writes/synchronous_commit
# are off because this database exists for the duration of one gate run and is
# thrown away; durability settings only buy crash recovery nobody wants here,
# and they dominate the cost of 163 schema clones.
#
# Neither gate names a host port. This machine runs many projects at once, and a
# fixed port is a standing appointment to collide with one of them: 55432 was
# already held by another project's Postgres and migrate-check died on the bind
# rather than on anything in the diff. `-p 127.0.0.1::5432` hands the choice to
# the kernel, which picks one that is free at that instant; `docker port` reads
# back which. Nothing outside the gate needs to reach these containers -- the
# DSN is built here and handed to the test process -- so the port never has to
# be predictable, only free.
REALDB_PG_CONTAINER := mcpdp-realdb-pg
REALDB_PG_IMAGE     := pgvector/pgvector:pg16
REALDB_TEMPLATE     := testdb_template
# REALDB_PKGS is what test-realdb runs: every package, unless realdb-lane
# narrows it to the packages a branch can break (#1947).
REALDB_PKGS         ?= ./...
# REALDB_RUN is the -run pattern: every RealDB test, unless route-template-diff
# names the one gate it needs (#2186).
REALDB_RUN          ?= RealDB
# REALDB_MAX_CONNECTIONS is the lane server's max_connections, set from what the
# packages open (#2249). -p 4 runs four packages at once, so the four largest
# package peaks bound the lane: 8+8+6+5 measured on 2026-10-21, plus the
# template and admin sessions, about 30. Before the migration wrapper returned
# its connection, pkg/oauth/postgres alone held 268 and a 400 limit was
# exhausted under make verify's load. The sampler test-realdb runs prints each
# run's peak and its largest packages.
REALDB_MAX_CONNECTIONS ?= 100

MIGRATE_PG_IMAGES := \
	pgvector/pgvector:pg16@sha256:00ba258a66dac104fd5171074a0084462a64a1369d8513f3d0a634e2f24d15bc \
	pgvector/pgvector:pg17@sha256:cf134a767f474095eeba57e0117be8e568e011a63f33fbf252f14c9b760f8e6f
MIGRATE_PG_CONTAINER := mcp-migrate-check-pg

## migrate-check: Apply all migrations + seed to a throwaway real Postgres, per major
migrate-check:
	@echo "Running real-Postgres migration gate..."
	@set -e; \
	trap 'docker rm -f $(MIGRATE_PG_CONTAINER) >/dev/null 2>&1 || true' EXIT; \
	for img in $(MIGRATE_PG_IMAGES); do \
		echo "  === $$img ==="; \
		docker rm -f $(MIGRATE_PG_CONTAINER) >/dev/null 2>&1 || true; \
		docker run -d --name $(MIGRATE_PG_CONTAINER) \
			-e POSTGRES_USER=migrate -e POSTGRES_PASSWORD=migrate -e POSTGRES_DB=migrate_check \
			-p 127.0.0.1::5432 $$img >/dev/null; \
		pg_port=$$(docker port $(MIGRATE_PG_CONTAINER) 5432/tcp | head -1 | sed 's/.*://'); \
		if [ -z "$$pg_port" ]; then echo "FAIL: could not read the published Postgres port" >&2; exit 1; fi; \
		echo "  waiting for Postgres on :$$pg_port..."; \
		for i in $$(seq 1 60); do \
			docker exec $(MIGRATE_PG_CONTAINER) pg_isready -h localhost -p 5432 -U migrate -d migrate_check >/dev/null 2>&1 && break; \
			if [ "$$i" = "60" ]; then echo "FAIL: Postgres did not become ready" >&2; exit 1; fi; \
			sleep 1; \
		done; \
		MIGRATE_TEST_DSN="postgres://migrate:migrate@localhost:$$pg_port/migrate_check?sslmode=disable" \
			$(GOTEST) -count=1 -run TestMigrationsAgainstRealPostgres ./pkg/database/migrate/; \
		docker rm -f $(MIGRATE_PG_CONTAINER) >/dev/null 2>&1 || true; \
	done
	@echo "Migration gate passed on every pinned major."

## coverage: Generate coverage report
coverage: test
	@echo "Generating coverage report..."
	$(GO) tool cover -html=coverage.out -o coverage.html
	@echo "Coverage report: coverage.html"

## lint: Run patch-scoped linter (matches CI's only-new-issues=true exactly)
##
## CI's golangci-lint-action runs with only-new-issues=true on every PR,
## reporting findings only on lines changed in the PR. This target
## mirrors that scope so local fails when CI would fail.
##
## CRITICAL: golangci-lint's --new-from-rev flag only sees COMMITTED
## changes, so before any commits the patch is empty and lint
## early-exits as a no-op — letting bad code reach the commit gate.
## This target generates a unified-diff patch from the merge-base
## that includes BOTH committed changes AND working-tree changes
## (staged + unstaged), then passes it via --new-from-patch. The
## patch-based path catches the same issues CI would, AND issues in
## uncommitted code, so `make verify` is a true pre-commit gate.
##
## Merge-base resolution: prefer origin/main (matches CI's PR base
## ref). Falls back to local main only if origin/main is not
## reachable (detached HEAD, fresh clone before fetch). If neither
## is reachable the patch lint warns and skips rather than silently
## passing.
##
## Use `make lint-full` to scan the entire codebase (housekeeping;
## not part of `make verify`).
lint:
	@echo "Running patch-scoped lint (matches CI only-new-issues, includes uncommitted changes)..."
	@# The cache is cleaned before the run: golangci-lint can serve a
	@# previously FILTERED result for an unchanged package, so a warm cache
	@# reports 0 issues on lines CI (which always runs cold) rejects. That
	@# cost us a red Lint job on PR 1303 after a green `make verify`, which
	@# is the same class of failure as #393 — a local gate that passes on
	@# something CI does not.
	@#
	@# Auto-fetch so a fresh clone or a stale local mirror doesn't bypass
	@# the gate. The fetch is shallow + quiet and tolerates network
	@# absence; if BOTH origin/main and main remain unreachable, we
	@# HARD FAIL rather than silently skip — silent skipping is exactly
	@# how a clean local make verify let lint issues reach CI in #393.
	@git fetch --quiet origin main 2>/dev/null || true
	@if git rev-parse origin/main >/dev/null 2>&1; then \
		BASE=origin/main; \
	elif git rev-parse main >/dev/null 2>&1; then \
		BASE=main; \
	else \
		echo "ERROR: neither origin/main nor main is reachable."; \
		echo "       Run \`git fetch origin main\` and retry."; \
		echo "       (lint MUST run against a base; silent-skip is a CI-parity hole.)"; \
		exit 1; \
	fi; \
	MERGE_BASE=$$(git merge-base $$BASE HEAD 2>/dev/null); \
	if [ -z "$$MERGE_BASE" ]; then \
		echo "ERROR: could not compute merge-base against $$BASE."; \
		echo "       Ensure the current branch shares history with $$BASE."; \
		exit 1; \
	fi; \
	PATCH=$$(mktemp -t mcpdp-lint-patch.XXXXXX); \
	trap "rm -f $$PATCH" EXIT; \
	git diff $$MERGE_BASE > $$PATCH; \
	if [ ! -s $$PATCH ]; then \
		echo "No changes vs merge-base ($$BASE); nothing to lint."; \
		echo "       (If you expected changes, confirm \`git log $$BASE..HEAD\` is non-empty.)"; \
		exit 0; \
	fi; \
	echo "Linting against merge-base $$MERGE_BASE (from $$BASE) — includes uncommitted changes"; \
	$(GOLINT) cache clean; \
	$(GOLINT) run --new-from-patch=$$PATCH ./...

## lint-full: Run linter against the ENTIRE codebase (not chained into verify)
##
## CI does not enforce findings on pre-existing code, so neither does
## `make verify`. This target exists for housekeeping passes.
lint-full:
	@echo "Running full-codebase linter (informational; not enforced by CI)..."
	$(GOLINT) run ./...

## lint-fix: Run linter with auto-fix
lint-fix:
	@echo "Running linter with auto-fix..."
	$(GOLINT) run --fix ./...

## vet-tags: Compile-check the build tags no default build sees
#
# A file behind `//go:build integration` is compiled by nothing cheap. Every
# other consumer of the tag wants a machine: test-integration wants the whole
# suite, test-realdb wants Docker and a migrated Postgres, smoke wants a
# running server, acceptance wants a dev stack and a renderer, frontend-e2e
# wants a stack. The cheap gates (lint, patch-coverage, schedule-lane, gosec,
# npm run build) all compile with the default tags, and .golangci.yml sets no
# build tags either, so none of them reads these files.
#
# The result was that a compile error in a tagged file was first reported by
# verify-docker, after the daemon had started and the migrations had replayed.
# On #1794 three tagged files referenced constants that had been removed; every
# cheap gate passed and the Docker lane failed six minutes in. This target
# answers the same question in about a second, which is why it sits in the
# serial preamble of `verify` rather than in a lane beside that Docker work.
#
# It is a compile, not a test: no container, no database, no stack.
vet-tags:
	@echo "Vetting the integration build..."
	@$(GOVET) -tags=integration ./...

## fmt: Format code
fmt:
	@echo "Formatting code..."
	$(GOFMT) -s -w .

## clean: Clean build artifacts
clean:
	@echo "Cleaning..."
	@rm -rf $(BUILD_DIR) $(DIST_DIR)
	@rm -f coverage.out coverage.html
	@rm -rf $(UI_DIR)/dist $(UI_DIR)/dist-content-viewer $(UI_DIR)/dist-content-viewer-css $(UI_DIR)/node_modules
	@# Reset embed dirs but keep .gitkeep
	@find $(UI_EMBED_DIR) -not -name '.gitkeep' -not -path $(UI_EMBED_DIR) -delete 2>/dev/null || true
	@find $(CV_EMBED_DIR) -not -name '.gitkeep' -not -path $(CV_EMBED_DIR) -delete 2>/dev/null || true
	@echo "Clean complete."

## install: Install the binary
install: build
	@echo "Installing $(BINARY_NAME)..."
	$(GO) install $(LDFLAGS) $(CMD_DIR)
	@echo "Installed."

## mod-tidy: Tidy go modules
mod-tidy:
	@echo "Tidying modules..."
	$(GOMOD) tidy

## mod-download: Download modules
mod-download:
	@echo "Downloading modules..."
	$(GOMOD) download

## mod-verify: Verify modules
mod-verify:
	@echo "Verifying modules..."
	$(GOMOD) verify

## security: Run security checks (gosec + govulncheck + osv-scanner)
security:
	@echo "Running gosec..."
	@# GOOS=linux reads the code with the types CI's Linux runner sees: a
	@# field typed differently by platform (syscall.Statfs_t.Bsize is int64 on
	@# Linux, uint32 on darwin) is otherwise judged locally on darwin's.
	@# Not -quiet: with it, gosec exits 0 when it cannot load a package, so a
	@# scan that analyzed nothing passes. CI runs it the same way.
	GOOS=linux gosec ./...
	@echo "Running govulncheck..."
	@# govulncheck exits 3 when our code calls a vulnerable symbol, whether or
	@# not a fixed version exists, and has no way to accept a finding. The gate
	@# judges the report against .govulncheck-allow.txt, where an accepted
	@# advisory carries the reason it is accepted and expires the moment a fix
	@# ships or the advisory stops being reported. CI runs the same two
	@# commands, so local and CI cannot disagree.
	@govulncheck -format json ./... > $(GOVULN_REPORT) 2>/dev/null; \
	status=$$?; \
	if [ $$status -ne 0 ] && [ $$status -ne 3 ]; then \
		echo "ERROR: govulncheck failed to run (exit $$status)"; \
		rm -f $(GOVULN_REPORT); \
		exit 1; \
	fi
	@python3 scripts/govulncheck-gate.py $(GOVULN_REPORT); \
	status=$$?; \
	rm -f $(GOVULN_REPORT); \
	exit $$status
	@$(MAKE) --no-print-directory osv

## osv: Fail on any known advisory against a manifest the platform ships from
## osv-scanner judges go.mod, the UI's npm lockfile and the docs site's
## requirements against the GitHub advisory database. Its Go call analysis
## drops an advisory whose symbols the module never calls; an npm or pip
## advisory counts whatever the code uses. An accepted advisory is listed in osv-scanner.toml with its
## reason and an ignoreUntil date; past that date the entry stops applying and
## the advisory fails the gate again, and an entry that no longer matches any
## finding fails it too, so the file cannot hold a stale acceptance. CI runs
## this target. bench/ and test/load/ are separate modules the release never
## builds and are not scanned.
OSV_MANIFESTS := -L go.mod -L $(UI_DIR)/package-lock.json -L docs/requirements.txt
OSV_LOG := build/osv-scanner.log
osv:
	@echo "Running osv-scanner..."
	@mkdir -p $(dir $(OSV_LOG))
	@osv-scanner scan source --config osv-scanner.toml $(OSV_MANIFESTS) > $(OSV_LOG) 2>&1; \
	status=$$?; \
	cat $(OSV_LOG); \
	if grep -q 'has unused ignores' $(OSV_LOG); then \
		echo "ERROR: osv-scanner.toml accepts an advisory no longer reported; delete that entry."; \
		status=1; \
	fi; \
	rm -f $(OSV_LOG); \
	exit $$status

## semgrep: Run Semgrep SAST with standard and custom rules
semgrep:
	@echo "Running Semgrep..."
	semgrep scan --config p/golang --config .semgrep/ --error --quiet .

## semgrep-diff: Run the diff-scoped Semgrep rules against changed lines
##
## .semgrep/ holds rules that are defects wherever they sit, so `semgrep` runs
## them over the whole tree. .semgrep-diff/ holds rules that refuse a SHAPE a
## diff-scoped CI check rejects with reasoning Semgrep cannot reproduce: the
## allocation-size rule matches 55 sites here and CodeQL flags none of them,
## because CodeQL knows which operands can be large and Semgrep does not.
##
## Scoping those to the diff is what CI already does with them -- Code Scanning
## reports against a pull request's changes -- and what `make lint` does with
## golangci-lint's --new-from-patch, off the same merge-base. Semgrep's own
## --baseline-commit aborts on an unstaged change, and `make verify` is a
## pre-commit gate run on exactly that, so the scoping lives in the script.
## Every rule file in the directory runs; test/gates/semgrep_diff_test.go holds
## each rule to the shape it was written for.
semgrep-diff:
	@echo "Running diff-scoped Semgrep..."
	@python3 scripts/semgrep-diff.py .semgrep-diff/

## semgrep-changed: Run the .semgrep/ rules over the Go files this branch changed (#2145)
##
## `semgrep` holds the whole tree to .semgrep/ in verify-static, one of the
## parallel lanes, so a finding there used to fail verify after the Go, Docker
## and UI lanes had run. The tree passes them on main, so a finding in a file
## the branch touched is the branch's: this reports it whole-file, in seconds,
## in preverify-fast.
semgrep-changed:
	@echo "Running .semgrep/ rules on changed files..."
	@python3 scripts/semgrep-diff.py --whole-files .semgrep/

## codeql: Run CodeQL analysis (requires codeql CLI)
codeql:
	@echo "Running CodeQL analysis..."
	@rm -rf /tmp/mcp-dp-codeql-db
	codeql database create /tmp/mcp-dp-codeql-db --language=go --source-root=. --overwrite
	@codeql database analyze /tmp/mcp-dp-codeql-db \
		--format=sarif-latest --output=codeql-results.sarif \
		codeql/go-queries:codeql-suites/go-security-and-quality.qls
	@# Gate logic lives in scripts/codeql-gate.py — it counts results
	@# with sarif level=error OR security-severity >= 7.0. The
	@# security-severity check matches what GitHub Code Scanning
	@# treats as a blocking alert in CI: without it, low-confidence
	@# taint findings (go/request-forgery, go/sql-injection,
	@# go/log-injection) surface as `level=note` locally but block
	@# the CodeQL step in CI. Local CI parity is the whole point of
	@# `make verify`.
	@python3 scripts/codeql-gate.py codeql-results.sarif

## sast: Run all SAST scanners (semgrep + codeql)
sast: semgrep codeql

## docker-build: Build Docker image
docker-build:
	@echo "Building Docker image..."
	docker build -t txn2/mcp-data-platform:$(VERSION) .
	docker tag txn2/mcp-data-platform:$(VERSION) txn2/mcp-data-platform:latest

## run: Run the server
run: build
	@echo "Running $(BINARY_NAME)..."
	$(BUILD_DIR)/$(BINARY_NAME)

## version: Show version
version:
	@echo "Version: $(VERSION)"
	@echo "Go Version: $(GO_VERSION)"
	@echo "Build Time: $(BUILD_TIME)"

## dead-code: Report unreachable functions (informational, not blocking)
dead-code:
	@echo "Checking for dead code..."
	@OUTPUT=$$(deadcode ./... 2>&1 | grep -v "^$$") || true; \
	if [ -n "$$OUTPUT" ]; then \
		echo "Dead code detected (review for false positives):"; \
		echo "$$OUTPUT"; \
	else \
		echo "No dead code found."; \
	fi

## mutate: Run mutation testing with 60% efficacy threshold
mutate:
	@echo "Running mutation testing..."
	gremlins unleash --workers 1 --timeout-coefficient 3 --threshold-efficacy 60 ./pkg/...

## coverage-report: Print coverage summary (fails below COVERAGE_MIN)
coverage-report: test
	@$(MAKE) --no-print-directory coverage-summary

## coverage-summary: Print the summary of the coverage.out already written (fails below COVERAGE_MIN)
## coverage-report runs the tests first. verify-go runs `test` once and then
## this, so a verify runs the race unit suite once rather than once per reader
## of its profile (#2053).
coverage-summary:
	@echo ""
	@echo "=== Coverage Summary ==="
	@$(GO) tool cover -func=coverage.out | tail -1
	@echo ""
	@TOTAL=$$($(GO) tool cover -func=coverage.out | tail -1 | awk '{gsub(/%/,"",$$3); print $$3}'); \
	if [ "$$(echo "$$TOTAL < $(COVERAGE_MIN).0" | bc -l)" = "1" ]; then \
		echo "FAIL: Total coverage $$TOTAL% is below $(COVERAGE_MIN)% threshold"; \
		exit 1; \
	fi
	@echo "Functions with 0% coverage:"
	@$(GO) tool cover -func=coverage.out | awk '{gsub(/%/,"",$$3); if ($$3+0 == 0 && $$1 != "total:") print $$0}' || true
	@echo ""
	@echo "Functions below $(PATCH_COVERAGE_MIN)% coverage:"
	@$(GO) tool cover -func=coverage.out | awk '{gsub(/%/,"",$$3); if ($$3+0 < $(PATCH_COVERAGE_MIN).0 && $$3+0 > 0 && $$1 != "total:") print $$0}' || true
	@echo "=== End Coverage ==="

## patch-coverage: Check coverage of changed lines vs main (fails below PATCH_COVERAGE_MIN)
patch-coverage: test
	@$(MAKE) --no-print-directory patch-coverage-check

## patch-coverage-check: Check the changed lines against the coverage.out already written
## The half of patch-coverage verify-go runs after its one `test` (#2053).
patch-coverage-check:
	@echo "Checking patch coverage..."
	@PATCH_COVERAGE_THRESHOLD=$(PATCH_COVERAGE_MIN) ./scripts/patch-coverage.sh

## docs-images-check: Resolve every image the docs pin to a digest against its registry (network and Docker; run by the E2E Nightly)
docs-images-check:
	@./scripts/docs-image-digests.sh docs

## doc-check: Fail on orphaned docs, unresolved doc links, or unregistered tool refs; warn on undocumented changes
doc-check:
	@./scripts/doc-check.sh

## acceptance-check: Warn when production Go changed with no test/acceptance file beside it
acceptance-check:
	@./scripts/acceptance-check.sh

## alert-rules-test: Run the promtool unit tests over deployments/observability/alert-rules.yaml (#1892)
## The rules ship as a ConfigMap, so the script extracts the groups first and
## runs promtool from the Prometheus image dev/docker-compose.yml pins (or a
## local promtool). Not in verify: it needs Docker or promtool.
alert-rules-test:
	@./scripts/alert-rules-test.sh

## state-readers-check: Warn when an API contract field or swagger.json changed and nothing under ui/src did (#1709)
state-readers-check:
	@python3 scripts/state-readers-check.py

## builtin-pages-check: Warn when a diff changes source a built-in knowledge page describes and not the page (#2200)
## Each page's source is listed in internal/platform/knowledgebuiltin/covers.txt.
## Every deployment serves the pages on its next start, and nothing compiles
## their prose. A warning for a human, blocking for an AI agent.
builtin-pages-check:
	@python3 scripts/builtin-pages-check.py

## e2e-copy-check: Fail when an e2e spec asserts UI copy the diff removed from ui/src (#1977)
## The Playwright suite runs only inside verify, after the full unit run, so a
## string a diff changed under ui/src and a spec still asserts used to fail
## verify fifteen minutes in. This reads both in under a second.
e2e-copy-check:
	@python3 scripts/e2e-copy-check.py

## docs-build: Build the documentation site with mkdocs --strict (#2138)
## The deploy workflow builds the site only after a merge to main, so a broken
## nav entry used to stop the site deploying with every gate green. This builds
## it the same way, in a virtualenv installed from docs/requirements.txt with
## --require-hashes (the deploy workflow's install), rebuilt when that file
## changes, so local and CI build with the same mkdocs and theme.
DOCS_VENV := build/docs-venv
DOCS_STAMP := $(DOCS_VENV)/.requirements.sha256
docs-build:
	@want=$$(shasum -a 256 docs/requirements.txt | cut -d' ' -f1); \
	if [ ! -x $(DOCS_VENV)/bin/mkdocs ] || [ "$$(cat $(DOCS_STAMP) 2>/dev/null)" != "$$want" ]; then \
		echo "Installing docs/requirements.txt into $(DOCS_VENV)..."; \
		rm -rf $(DOCS_VENV) && python3 -m venv $(DOCS_VENV) && \
		$(DOCS_VENV)/bin/pip install --quiet --require-hashes -r docs/requirements.txt && \
		echo "$$want" > $(DOCS_STAMP) || exit 1; \
	fi
	@$(DOCS_VENV)/bin/mkdocs build --strict --site-dir build/docs-site

## route-manifest-check: Fail when a portal route has no screenshot manifest entry (#2055)
## route-sync.test.ts reads AppShell's pageTitles and the screenshot route
## manifest and finishes in milliseconds, but the full vitest suite inside
## verify's UI lane was the only thing running it, so a new portal section
## missing its entry failed verify minutes in. This runs that one file.
route-manifest-check:
	cd $(UI_DIR) && npx vitest run e2e/screenshots/route-sync.test.ts

## route-conformance-check: Fail when a mocked UI route is absent from swagger.json (#2186)
## route-conformance.test.ts reads the MSW handlers and internal/apidocs/swagger.json
## in under a second; like route-sync.test.ts, only the full vitest suite in verify's
## UI lane ran it, so a mock for a route the API does not describe failed verify.
route-conformance-check:
	cd $(UI_DIR) && npx vitest run src/mocks/route-conformance.test.ts

## schedule-lane: Run the tests the diff touched at -race -cpu=1,2 -count=5 (ordering-dependent tests, #1711, #2039)
## `test` runs each test once at this machine's CPU count, which is not the
## schedule a loaded CI runner chooses. TestWithRevocations_WiredLate passed
## two verify runs on 18 cores and fails 140 of 300 runs at -cpu=1. The lane
## runs the Test functions in the changed _test.go files, not their whole
## packages: ten passes of pkg/platform ran an hour on one core and then hit
## the lane's timeout in CI (#2039). Each package has ten minutes. CI runs
## this same target on every pull request.
schedule-lane:
	@python3 scripts/schedule-lane.py go

## schedule-lane-ui: Run the vitest suite with every changed *.test.ts(x) file run five times beside it (#1711)
## An assertion on a count recorded in a useEffect passed on an idle machine
## and failed CI's Frontend Build job; the repeats run while the suite loads
## the machine. It runs the full suite, so verify-ui calls it in place of
## frontend-test.
schedule-lane-ui:
	@python3 scripts/schedule-lane.py ui

## acceptance: Run the per-ticket acceptance suite as a real MCP client against a running server (make dev)
## Each test/acceptance/issue_<n>_test.go executes one ticket's acceptance
## criteria through the tool surface a user calls. It fails, rather than
## skips, when no server answers. Override the target with MCP_BASE_URL and
## MCP_API_KEY (defaults: the proxy in front of the dev stack's two replicas on
## DEV_PROXY_PORT, or the single dev server on DEV_API_PORT under
## DEV_REPLICAS=1, and the dev API key; #1708).
## ACCEPTANCE_TIMEOUT bounds the whole binary, not one test. Go's default is
## 10 minutes and the suite runs for most of that against a healthy stack --
## several criteria wait past a cadence that fires every minute, and several
## wait on a background index -- so the default kills the run
## partway through and reports the tests that were still on the clock as
## failures. A run that was cut short is not a suite that failed (#1632).
## The whole suite runs for well over two hours (#2218): #2111 alone writes
## four 1,500-file backfills at the tool-call limiter's pace of 4 a second.
ifeq ($(ISSUE),)
ACCEPTANCE_TIMEOUT ?= 240m
else
ACCEPTANCE_TIMEOUT ?= 40m
endif
## ISSUE=<n> runs one ticket's criteria (-run TestIssue<n>_) instead of the
## whole suite. Either way the run is recorded as a go test -json stream at
## build/<n>/acceptance.jsonl per ticket, which is the evidence make
## acceptance-check and make verify-release read: a criterion that did not run
## leaves no pass event, and no prose can supply one (#1680).
## Criteria that need a stack `make dev` does not make are named in
## test/acceptance/environments.txt (#2219): the whole suite leaves them out
## and says which, and ACCEPTANCE_ENV=<name> runs one environment's criteria
## instead (scripts/release-acceptance.sh starts the stack it needs).
## ACCEPTANCE_SHARD=i/N runs group i of N of the plain stack's criteria, split
## by ticket number, which is how the E2E Nightly runs the suite in N jobs at
## once (#2218).
# The recipe sets pipefail so a failed `go test` is not hidden by the evidence
# splitter it pipes into. Make runs recipes with /bin/sh, which is bash on
# macOS and dash on the Ubuntu runners, and dash has no pipefail, so every
# nightly group refused to start the suite (#2266).
acceptance: SHELL := /bin/bash
acceptance:
	@# dev/start.sh relocates the stack when the default ports are busy and
	@# records where it went; the suite follows it unless MCP_BASE_URL is set.
	@set -a; [ -f dev/.dev-ports.env ] && . ./dev/.dev-ports.env; set +a; \
	echo "Running acceptance suite against $${MCP_BASE_URL:-http://localhost:$${DEV_PROXY_PORT:-$${DEV_API_PORT:-8080}}}..."; \
	if [ -n "$(ISSUE)" ]; then run_flag="-run TestIssue$(ISSUE)_"; echo "  limited to #$(ISSUE)"; \
	elif [ -n "$(ACCEPTANCE_SHARD)" ]; then run_flag=$$(python3 scripts/acceptance-env.py flags "$(ACCEPTANCE_ENV)" --shard "$(ACCEPTANCE_SHARD)") || exit 1; echo "  group $(ACCEPTANCE_SHARD)"; \
	else run_flag=$$(python3 scripts/acceptance-env.py flags "$(ACCEPTANCE_ENV)") || exit 1; fi; \
	set -o pipefail; \
	eval "$(GOTEST) -count=1 -timeout $(ACCEPTANCE_TIMEOUT) -tags=integration ./test/acceptance/ -v -json $$run_flag" \
		| python3 scripts/acceptance-evidence.py split

## dev-smoke: One call through the platform per service the dev stack runs, in under a minute (#2248)
## A managed resource read back by digest (the TLS store), a portal asset read
## back (the plain store), a query on each scratch catalog, a Keycloak sign-in,
## a search hit on a just-embedded asset (Ollama) and a drawn tile (renderer):
## test/acceptance/devsmoke_test.go. With no stack answering it fails and says so.
dev-smoke:
	@set -a; [ -f dev/.dev-ports.env ] && . ./dev/.dev-ports.env; set +a; \
	base="$${MCP_BASE_URL:-http://localhost:$${DEV_PROXY_PORT:-$${DEV_API_PORT:-8080}}}"; \
	if ! curl -sf -o /dev/null --max-time 5 "$$base/healthz"; then \
		echo "dev-smoke: no dev stack answers at $$base; start one with make dev" >&2; exit 1; fi; \
	echo "dev-smoke: checking the dev stack at $$base"; \
	$(GOTEST) -count=1 -timeout 2m -tags=integration ./test/acceptance/ -run '^TestDevSmoke_'

## dev-smoke-diff: Run dev-smoke when the diff against main changes a file under dev/ (#2248)
DEV_DIR := dev
dev-smoke-diff:
	@base=$$(git merge-base origin/main HEAD 2>/dev/null || git merge-base main HEAD); \
	changed=$$( { git diff --name-only $$base -- $(DEV_DIR); git ls-files --others --exclude-standard -- $(DEV_DIR); } | sort -u); \
	if [ -z "$$changed" ]; then echo "dev-smoke-diff: nothing under dev/ changed; skipped"; exit 0; fi; \
	echo "dev-smoke-diff: $$(echo $$changed | wc -w | tr -d ' ') file(s) under dev/ changed"; \
	$(MAKE) --no-print-directory dev-smoke

## acceptance-release: The whole acceptance suite against the dev stack, whether or not one is up (#1969)
## The E2E Nightly runs it (in groups, ACCEPTANCE_SHARD) and a tag requires
## that nightly green; verify-release does not run it, because the suite runs
## for well over an hour and a release waits on nothing that long (#2218). A
## stack already answering is used as it is and left running; with none, one
## is started, the suite runs, and the stack it started is stopped (data kept).
acceptance-release:
	@bash scripts/release-acceptance.sh

## acceptance-release-check: Refuse a release whose tickets have no passing acceptance run
## Every test/acceptance/issue_<n>_test.go changed since the last tag must have
## a recorded run at build/<n>/acceptance.jsonl in which every criterion passed.
acceptance-release-check:
	@python3 scripts/acceptance-evidence.py release

## posture-check: Fail when README/llms.txt engineering-posture claims go stale
posture-check:
	@./scripts/posture-check.sh

## release-tag-check: Check a release tag against the release-candidate and E2E Nightly rules before pushing it (TAG=v1.139.0)
release-tag-check:
	@test -n "$(TAG)" || { echo "usage: make release-tag-check TAG=vX.Y.Z or TAG=vX.Y.Z-rcN"; exit 1; }
	@python3 scripts/release-tag.py check "$(TAG)"

## release-check: Validate build, Docker, and release config
release-check:
	@echo "Running GoReleaser dry-run..."
	goreleaser release --snapshot --clean --skip=publish,sign,sbom

## swagger: Generate OpenAPI/Swagger documentation from annotations
swagger:
	@echo "Generating Swagger docs..."
	@rm -f internal/apidocs/docs.go internal/apidocs/swagger.json internal/apidocs/swagger.yaml
	swag init --generalInfo pkg/admin/handler.go --dir . --output internal/apidocs --parseDependency
	@echo "Injecting tag descriptions and x-tagGroups..."
	@python3 scripts/swagger-tag-groups.py internal/apidocs
	@echo "Swagger docs generated in internal/apidocs/"

## swagger-check: Verify Swagger docs are up to date
swagger-check: swagger
	@if git diff --quiet internal/apidocs/; then \
		echo "Swagger docs are up to date"; \
	else \
		echo "ERROR: Swagger docs are out of date. Run 'make swagger' and commit."; \
		exit 1; \
	fi

## apidocs-openapi3-check: Convert internal/apidocs/swagger.json to OpenAPI 3, as the UI's type generation does
## A document swag writes can still be one swagger2openapi refuses (an optional
## path parameter, #2022), and ui/src/api/generated is gitignored, so nothing
## else converts it. This runs the conversion `npm run generate-api-types` runs.
apidocs-openapi3-check:
	@out=$$(mktemp -t openapi3.XXXXXX) && \
	  (cd $(UI_DIR) && npx --no-install swagger2openapi ../internal/apidocs/swagger.json -o "$$out") ; \
	  rc=$$? ; rm -f "$$out" ; \
	  if [ $$rc -ne 0 ]; then echo "ERROR: internal/apidocs/swagger.json does not convert to OpenAPI 3 (npm run generate-api-types would fail)."; exit 1; fi ; \
	  echo "internal/apidocs/swagger.json converts to OpenAPI 3"

## tools-check: Verify all required tools are installed AND pinned to CI versions
##
## Local-vs-CI tool version drift is the most insidious parity gap: different
## golangci-lint or gosec versions enable different rules with different
## defaults, so `make verify` can pass locally while CI rejects the same
## diff. Concrete incident on 2026-05-08: local gosec 2.26.1 silently dropped
## the G704 SSRF taint rule that CI's pinned v2.22.0 enforces, letting an
## actual SSRF bug ship to PR #377. See feedback_gate_metric.md.
##
## A matching version is not enough: CI installs with GOTOOLCHAIN=local, so a
## pin whose module needs a newer Go than CI sets up fails CI's install while a
## local GOTOOLCHAIN=auto install builds it. scripts/tools-go-check.sh refuses a
## pinned tool built with a newer Go than ci.yml's go-version (#2147), and every
## install command printed here sets GOTOOLCHAIN=local, as CI does.
tools-check:
	@echo "Checking required tools (presence AND pinned versions)..."
	@missing=""; mismatch=""; \
	if ! which golangci-lint > /dev/null 2>&1; then \
		missing="$$missing  golangci-lint: GOTOOLCHAIN=local go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@$(GOLANGCI_LINT_VERSION)\n"; \
	else \
		v=$$(go version -m $$(which golangci-lint) 2>/dev/null | awk '$$1=="mod" && $$2 ~ /golangci-lint/ {print $$3}'); \
		if [ -z "$$v" ] || [ "$$v" = "(devel)" ]; then \
			v=$$(golangci-lint version 2>&1 | grep -oE 'v?[0-9]+\.[0-9]+\.[0-9]+' | head -1); \
			case "$$v" in v*) ;; *) v="v$$v";; esac; \
		fi; \
		if [ "$$v" != "$(GOLANGCI_LINT_VERSION)" ]; then \
			mismatch="$$mismatch  golangci-lint: have $$v, want $(GOLANGCI_LINT_VERSION) — GOTOOLCHAIN=local go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@$(GOLANGCI_LINT_VERSION)\n"; \
		fi; \
	fi; \
	if ! which gosec > /dev/null 2>&1; then \
		missing="$$missing  gosec: GOTOOLCHAIN=local go install github.com/securego/gosec/v2/cmd/gosec@$(GOSEC_VERSION)\n"; \
	else \
		v=$$(go version -m $$(which gosec) 2>/dev/null | awk '$$1=="mod" && $$2 ~ /gosec/ {print $$3}'); \
		if [ -z "$$v" ] || [ "$$v" = "(devel)" ]; then \
			v=$$(gosec --version 2>&1 | grep -oE 'Version: v?[0-9]+\.[0-9]+\.[0-9]+' | grep -oE 'v?[0-9]+\.[0-9]+\.[0-9]+' | head -1); \
			case "$$v" in v*) ;; *) v="v$$v";; esac; \
		fi; \
		if [ "$$v" != "$(GOSEC_VERSION)" ]; then \
			mismatch="$$mismatch  gosec: have $$v, want $(GOSEC_VERSION) — GOTOOLCHAIN=local go install github.com/securego/gosec/v2/cmd/gosec@$(GOSEC_VERSION)\n"; \
		fi; \
	fi; \
	if ! which govulncheck > /dev/null 2>&1; then \
		missing="$$missing  govulncheck: GOTOOLCHAIN=local go install golang.org/x/vuln/cmd/govulncheck@$(GOVULNCHECK_VERSION)\n"; \
	else \
		v=$$(go version -m $$(which govulncheck) 2>/dev/null | awk '$$1=="mod" && $$2=="golang.org/x/vuln" {print $$3}'); \
		if [ -n "$$v" ] && [ "$$v" != "$(GOVULNCHECK_VERSION)" ]; then \
			mismatch="$$mismatch  govulncheck: have $$v, want $(GOVULNCHECK_VERSION) — GOTOOLCHAIN=local go install golang.org/x/vuln/cmd/govulncheck@$(GOVULNCHECK_VERSION)\n"; \
		fi; \
	fi; \
	if ! which osv-scanner > /dev/null 2>&1; then \
		missing="$$missing  osv-scanner: GOTOOLCHAIN=local go install github.com/google/osv-scanner/v2/cmd/osv-scanner@$(OSV_SCANNER_VERSION)\n"; \
	else \
		v=$$(osv-scanner --version 2>&1 | grep -oE 'version: v?[0-9]+\.[0-9]+\.[0-9]+' | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1); \
		if [ "v$$v" != "$(OSV_SCANNER_VERSION)" ]; then \
			mismatch="$$mismatch  osv-scanner: have v$$v at $$(which osv-scanner), want $(OSV_SCANNER_VERSION) — GOTOOLCHAIN=local go install github.com/google/osv-scanner/v2/cmd/osv-scanner@$(OSV_SCANNER_VERSION), ahead of any other copy on PATH\n"; \
		fi; \
	fi; \
	if ! newer=$$(sh scripts/tools-go-check.sh .github/workflows/ci.yml \
		golangci-lint=github.com/golangci/golangci-lint/v2/cmd/golangci-lint@$(GOLANGCI_LINT_VERSION) \
		gosec=github.com/securego/gosec/v2/cmd/gosec@$(GOSEC_VERSION) \
		govulncheck=golang.org/x/vuln/cmd/govulncheck@$(GOVULNCHECK_VERSION) \
		osv-scanner=github.com/google/osv-scanner/v2/cmd/osv-scanner@$(OSV_SCANNER_VERSION) \
		gremlins=github.com/go-gremlins/gremlins/cmd/gremlins@$(GREMLINS_VERSION)); then \
		mismatch="$$mismatch$$newer\n"; \
	fi; \
	which semgrep > /dev/null 2>&1       || missing="$$missing  semgrep: pip3 install semgrep\n"; \
	which codeql > /dev/null 2>&1        || missing="$$missing  codeql: brew install codeql\n"; \
	which deadcode > /dev/null 2>&1      || missing="$$missing  deadcode: GOTOOLCHAIN=local go install golang.org/x/tools/cmd/deadcode@latest\n"; \
	if ! which gremlins > /dev/null 2>&1; then \
		missing="$$missing  gremlins: GOTOOLCHAIN=local go install github.com/go-gremlins/gremlins/cmd/gremlins@$(GREMLINS_VERSION)\n"; \
	else \
		v=$$(go version -m $$(which gremlins) 2>/dev/null | awk '$$1=="mod" && $$2 ~ /gremlins/ {print $$3}'); \
		if [ -z "$$v" ] || [ "$$v" = "(devel)" ]; then \
			v=$$(gremlins --version 2>&1 | grep -oE 'v?[0-9]+\.[0-9]+\.[0-9]+' | head -1); \
			case "$$v" in v*) ;; *) v="v$$v";; esac; \
		fi; \
		if [ "$$v" != "$(GREMLINS_VERSION)" ]; then \
			mismatch="$$mismatch  gremlins: have $$v, want $(GREMLINS_VERSION) — GOTOOLCHAIN=local go install github.com/go-gremlins/gremlins/cmd/gremlins@$(GREMLINS_VERSION)\n"; \
		fi; \
	fi; \
	which goreleaser > /dev/null 2>&1    || missing="$$missing  goreleaser: brew install goreleaser\n"; \
	node_want=$$(tr -d ' \n' < $(UI_DIR)/.nvmrc); \
	if ! which node > /dev/null 2>&1; then \
		missing="$$missing  node: nvm install $$node_want (the major in $(UI_DIR)/.nvmrc, which CI installs)\n"; \
	else \
		node_have=$$(node --version | sed -E 's/^v([0-9]+).*/\1/'); \
		if [ "$$node_have" != "$$node_want" ]; then \
			mismatch="$$mismatch  node: have major $$node_have, want $$node_want (the major in $(UI_DIR)/.nvmrc, which CI installs) — nvm install $$node_want && nvm use $$node_want\n"; \
		fi; \
	fi; \
	which swag > /dev/null 2>&1          || missing="$$missing  swag: GOTOOLCHAIN=local go install github.com/swaggo/swag/cmd/swag@latest\n"; \
	if [ -n "$$missing" ]; then \
		echo ""; \
		echo "FAIL: Missing required tools:"; \
		printf '%b' "$$missing"; \
		echo ""; \
		echo "Install all missing tools before running make verify."; \
		exit 1; \
	fi; \
	if [ -n "$$mismatch" ]; then \
		echo ""; \
		echo "FAIL: Tool version mismatch (local differs from CI-pinned)."; \
		echo "Local versions that drift from CI's create silent parity gaps:"; \
		echo "make verify can pass while CI rejects the same diff."; \
		echo ""; \
		printf '%b' "$$mismatch"; \
		echo ""; \
		echo "Pin local tools to the CI versions before running make verify."; \
		echo "(Override with TOOLS_CHECK_STRICT=0 only if you know what you are doing.)"; \
		if [ "$(TOOLS_CHECK_STRICT)" != "0" ]; then exit 1; fi; \
		echo "WARN: proceeding with mismatched tool versions (TOOLS_CHECK_STRICT=0)."; \
	else \
		echo "All required tools found at pinned CI versions."; \
	fi

## embed-clean: Reset UI embed dirs to .gitkeep only (matches CI clean checkout)
embed-clean:
	@echo "Cleaning UI embed directories..."
	@find $(UI_EMBED_DIR) -not -name '.gitkeep' -not -path $(UI_EMBED_DIR) -delete 2>/dev/null || true
	@find $(CV_EMBED_DIR) -not -name '.gitkeep' -not -path $(CV_EMBED_DIR) -delete 2>/dev/null || true

## verify-release: Full verify PLUS CodeQL and mutation testing — run only before cutting a release
## Both are expensive and must NOT run per-revision; CI runs each on the PR.
## The release's own tickets must have a passing acceptance run
## (acceptance-release-check); the whole suite is the E2E Nightly's, which the
## tag check requires green (#2218).
verify-release: verify codeql mutate acceptance-release-check
	@echo ""
	@echo "=== Release verification complete (incl. CodeQL, mutation testing and the release's acceptance runs) ==="

## verify: Run the CI-equivalent per-commit suite (test, lint, security, SAST, coverage, release)
## NOTE: mutation testing and CodeQL are intentionally excluded — both live in
## verify-release, and CI runs each on the pull request. Do not add `mutate` or
## `codeql` back to this per-commit target; see the comment in the recipe.
verify:
	@# The steps that REWRITE the working tree run first, one at a time,
	@# because everything after them reads what they produce: fmt rewrites
	@# sources, embed-clean empties the UI embed directories, and
	@# swagger-check, the first step of preverify-fast below, regenerates
	@# internal/apidocs before any gate reads it. Each is its own $(MAKE)
	@# line, so they stay ordered even when the outer make was given -j.
	@$(MAKE) --no-print-directory tools-check
	@$(MAKE) --no-print-directory fmt
	@$(MAKE) --no-print-directory embed-clean
	@# Then the tagged build, before the lanes fan out. It is here rather than
	@# inside verify-static because the lanes start together under -j4: a failure
	@# reported from a lane does not stop verify-docker from having already
	@# brought up the daemon and replayed the migrations. One second of serial
	@# wall clock buys a broken integration-tagged file being reported before
	@# any of that begins (#1799).
	@$(MAKE) --no-print-directory vet-tags
	@# Then the diff-scoped gates that read the change rather than a coverage
	@# profile (#1856): about fifteen seconds together. They used to run at the
	@# END of verify-go, behind the full race+coverage unit run, so a finding
	@# in one was reported thirteen minutes in and cost a second full run to
	@# learn whether the rest of the lane passed.
	@$(MAKE) --no-print-directory preverify-fast
	@# Then lint, still serial and before any lane starts. It used to run in
	@# the lint lane beside the full unit run, so a lint finding was
	@# reported only after every lane had been started, and the run it cost
	@# was the whole of verify. Two minutes here answers it first.
	@$(MAKE) --no-print-directory lint
	@# CodeQL is deliberately NOT here. It cannot join the concurrent phase:
	@# its Go extractor uses autobuild, which finds this Makefile and runs the
	@# default goal, so the step quietly regenerates swagger, runs the whole
	@# test suite and lints a second time. That is harmless alone and
	@# destructive beside anything else — it deleted internal/apidocs/swagger.json
	@# while another group was compiling. Narrowing the extractor with
	@# --command would shrink what is analysed and split local from CI.
	@#
	@# So it could only ever run alone, ahead of everything, and measured on
	@# this repo that is ~4 minutes of serial wall clock added to every single
	@# commit — the largest cost in the target by a wide margin, and more than
	@# the whole concurrent phase.
	@#
	@# It buys nothing that is not already bought. .github/workflows/codeql.yml
	@# runs the same security-and-quality suite on every pull_request to main
	@# and blocks the merge, so a finding is caught before anything ships; the
	@# local copy only changes whether you learn about it now or at PR time.
	@# This is the same trade already made for mutation testing, and it lives
	@# in the same place: verify-release, plus `make codeql` on demand.
	@$(MAKE) --no-print-directory -j4 verify-checks
	@echo ""
	@echo "=== All checks passed ==="
	@# Write the gate sentinel: the id of a tree built from the working copy at
	@# the moment verify completed. The pre-commit review gate
	@# (~/.claude/hooks/review-gate.sh) recomputes it at commit time — if they
	@# match, this verify run is proof CI-equivalent checks passed on the exact
	@# code being committed.
	@#
	@# It is a tree id rather than a hash of `git diff`, and that is not a style
	@# choice: a diff does not mention an untracked file, so a brand-new source
	@# file written after a green run left the old hash unchanged and was waved
	@# through unverified, while `git add`-ing that same file changed the hash
	@# and rejected a tree verify had passed on. A tree built with `git add -A`
	@# sees the file either way.
	@#
	@# Hash computation MUST stay byte-identical to compute_diff_hash() in
	@# review-gate.sh. When the two drift, the sentinel becomes a value the two
	@# readers disagree about and the gate rejects EVERY commit.
	@mkdir -p .claude
	@dir=$$(mktemp -d); \
		git read-tree --index-output=$$dir/index HEAD 2>/dev/null; \
		GIT_INDEX_FILE=$$dir/index git add -A 2>/dev/null; \
		GIT_INDEX_FILE=$$dir/index git write-tree 2>/dev/null \
			| cut -c1-16 > .claude/.last-verify-passed; \
		rm -rf $$dir
	@echo "Wrote .claude/.last-verify-passed (gate sentinel)"

## verify-checks: the read-only half of `verify`, run concurrently by it.
##
## Each lane prints a "[lane start/done]" marker. The wall clock of `verify` is
## the slowest lane, so those two lines are what tell you which lane to attack
## when the cycle gets slow — without them the lanes interleave into one
## undifferentiated stream and the pole is guesswork.
##
## The steps are grouped by the resource they contend for, NOT spread evenly:
## a flat -j starves whatever it oversubscribes. Each group runs its own steps
## in order; the groups run at once, so the wall clock is the slowest group
## rather than the sum of everything.
##
## The groupings are not arbitrary. Each one exists because running its members
## beside something else was tried and broke:
##
##   - release-check runs `npm ci` in goreleaser's before-hook, which deletes
##     and reinstalls ui/node_modules. Beside the e2e suite that removes
##     @playwright/test mid-run. It therefore shares a group with the frontend
##     steps and goes last in it. The Go lane used to be exposed to the same
##     deletion from the other side — one npm dependency ships a Go package
##     inside node_modules, so `go test ./...` compiled it and an ill-timed
##     `npm ci` failed the run on a file that had vanished. ui/go.mod takes
##     that directory out of the root module, so the two lanes no longer share
##     it; see the comment in that file. GoReleaser's --clean likewise removes
##     and recreates its output directory while the Docker lane's
##     `go test -tags=integration ./...` walks the module; that directory is
##     named _dist (.goreleaser.yml) because the go tool skips a "_"-prefixed
##     directory when it expands ./..., so the walk never opens it (#2042).
##   - test-realdb starts a Postgres container per test and runs them in
##     parallel; 20 were live at once here. Beside goreleaser's five-platform
##     build and CodeQL it starved the Docker daemon into `context deadline
##     exceeded` while inspecting a starting container. Docker work gets one
##     group and nothing else in the schedule competes for the daemon.
##   - golangci-lint refuses to start while another instance is running, so the
##     two lint steps share a group (see verify-static).
## CodeQL is not here at all: its extractor runs the Makefile's default goal,
## which rewrites generated files, so `verify` runs it before this phase.
##
##   - verify-ui runs after verify-static, in one lane with it (#2243).
##     schedule-lane-ui runs each changed vitest file five times beside the
##     full suite under vitest's 5-second per-test timeout, and the Go lanes
##     only slow down under CPU starvation where a vitest test times out: with
##     every lane starting together on a cold build cache the load average
##     reached 465 on 18 cores and a test that takes 80ms alone took 8.9s.
##     verify-static is the shortest lane, so the UI half still runs beside
##     verify-go and verify-docker instead of adding its length to verify.
##
## Run it directly to re-check without the formatting and generation steps.
verify-checks: verify-go verify-static-ui verify-docker
	@:

## verify-static-ui: verify-static, then verify-ui, in one lane (#2243).
verify-static-ui:
	@$(MAKE) --no-print-directory verify-static
	@$(MAKE) --no-print-directory verify-ui

## verify-go: the Go checks that read the tree and the coverage profile.
## coverage-summary and patch-coverage-check both read the coverage.out that
## `test` writes, which is why this group is ordered rather than parallel. They
## are the halves of coverage-report and patch-coverage that do not run the
## tests again: each $(MAKE) line is its own invocation and does not know
## `test` already ran, so naming the targets with `test` as a prerequisite ran
## the race unit suite three times per verify (#2053).
verify-go:
	@echo "[lane start $$(date +%T)] verify-go"
	@# The schedule lane runs first (#1856): it covers only the changed
	@# packages, so a failing changed test is reported in minutes rather than
	@# after the whole module's unit run. The lane's length is unchanged.
	@$(MAKE) --no-print-directory schedule-lane
	@$(MAKE) --no-print-directory test
	@$(MAKE) --no-print-directory coverage-summary
	@$(MAKE) --no-print-directory patch-coverage-check
	@$(MAKE) --no-print-directory bench-test
	@$(MAKE) --no-print-directory bench-report-check
	@echo "[lane done  $$(date +%T)] verify-go"

## preverify-fast: the cheap gates verify runs before its lanes (#1856, #2030)
## swagger-check and apidocs-openapi3-check (the API description is current and
## converts to OpenAPI 3), semgrep-diff, semgrep-changed, doc-check, acceptance-check,
## state-readers-check, builtin-pages-check, e2e-copy-check, route-manifest-check,
## route-conformance-check, dead-code and frontend-lint read the change and the tree, not a coverage profile, so they answer in under a
## minute. verify runs them in its serial preamble. swagger-check runs first
## because it rewrites internal/apidocs, which state-readers-check reads.
preverify-fast:
	@$(MAKE) --no-print-directory swagger-check
	@$(MAKE) --no-print-directory apidocs-openapi3-check
	@$(MAKE) --no-print-directory semgrep-diff
	@$(MAKE) --no-print-directory semgrep-changed
	@$(MAKE) --no-print-directory doc-check
	@$(MAKE) --no-print-directory docs-build
	@$(MAKE) --no-print-directory acceptance-check
	@$(MAKE) --no-print-directory state-readers-check
	@$(MAKE) --no-print-directory builtin-pages-check
	@$(MAKE) --no-print-directory e2e-copy-check
	@$(MAKE) --no-print-directory route-manifest-check
	@$(MAKE) --no-print-directory route-conformance-check
	@$(MAKE) --no-print-directory dead-code
	@$(MAKE) --no-print-directory frontend-lint

## realdb-lane: Run the RealDB tests of every changed package and every package importing one (#1947)
## make preverify runs no test behind the integration build tag, so a change
## that broke a real-database test was first reported by verify's Docker lane
## (#1913: three pkg/platform tests creating scripts the save gates refused).
## scripts/realdb-lane.py names the packages; test-realdb runs them against
## one Postgres. Nothing to run is not a failure.
realdb-lane:
	@pkgs="$$(python3 scripts/realdb-lane.py)"; \
	if [ -z "$$pkgs" ]; then echo "realdb-lane: no changed package has a RealDB test to run"; exit 0; fi; \
	echo "realdb-lane: $$(echo $$pkgs | wc -w | tr -d ' ') package(s)"; \
	$(MAKE) --no-print-directory test-realdb REALDB_PKGS="$$pkgs" || { \
		echo "realdb-lane: reproduce with: make test-realdb REALDB_PKGS=\"$$pkgs\"" >&2; exit 1; }

## preverify: the gates that decide most verify failures, in minutes (#1856)
## preverify-fast, the patch-scoped lint, both halves of the schedule lane
## (the changed Go packages, then the changed vitest files beside the full
## suite, #1929), and the RealDB tests of the changed packages and every
## package importing one (#1947). A branch that passes it fails verify only on
## the full unit run, coverage, security, the rest of the real-DB lane, or the
## rest of the UI lane.
## preverify: The cheap gates and the patch-scoped lint, under a few minutes (#1856, #2039)
## It runs nothing verify runs again in full: the schedule lane, its UI half and
## the real-DB lane used to follow lint here (#1929, #1947) and on a change to
## pkg/platform they cost as much as verify itself, so a pre-gate was no longer
## one. Those three run once, in verify and in CI. What it adds to lint is scoped
## to the diff (#2186, #2239, #2248): gosec over the changed packages, migrate-check
## when a migration changed, the route-template gate when a mux registration
## changed, and dev-smoke when a file under dev/ changed.
preverify: preverify-fast
	@$(MAKE) --no-print-directory lint
	@$(MAKE) --no-print-directory security-diff
	@$(MAKE) --no-print-directory migrate-check-diff
	@$(MAKE) --no-print-directory route-template-diff
	@$(MAKE) --no-print-directory dev-smoke-diff

## security-diff: Run the standalone gosec over the packages the diff changes (#2186)
## verify-static runs `gosec ./...`, which reads #nosec and not //nolint:gosec, so a
## finding the patch lint passes failed verify. Same invocation, changed packages only.
security-diff:
	@pkgs="$$(python3 scripts/preverify-diff.py gosec-packages)"; \
	if [ -z "$$pkgs" ]; then echo "security-diff: no production Go file changed; skipped"; exit 0; fi; \
	echo "security-diff: gosec over $$(echo $$pkgs | wc -w | tr -d ' ') package(s)"; \
	GOOS=linux gosec $$pkgs

## route-template-diff: Run the route-template gate when the diff changes a mux registration (#2186)
## TestEveryRouteReportsItsTemplate_RealDB fails a registration the test platform does
## not mount, or one that reports no template, and ran only in verify's Docker lane.
route-template-diff:
	@if ! python3 scripts/preverify-diff.py routes-changed; then \
		echo "route-template-diff: no route registration changed; skipped"; exit 0; fi; \
	$(MAKE) --no-print-directory test-realdb REALDB_PKGS=./internal/httpserver/ REALDB_RUN=TestEveryRouteReportsItsTemplate_RealDB

## migrate-check-diff: Run migrate-check when the diff against main adds or changes a migration (#2239)
## The RealDB tests run on pg16 alone, so a migration PostgreSQL 17 refuses
## (#2169's 000209: an index function called by an unqualified name, which an
## index build on 17 resolves under search_path pg_catalog) passed every test
## and failed verify's Docker lane. A diff with no migration skips it.
MIGRATIONS_DIR := pkg/database/migrate/migrations
migrate-check-diff:
	@base=$$(git merge-base origin/main HEAD 2>/dev/null || git merge-base main HEAD); \
	changed=$$( { git diff --name-only $$base -- $(MIGRATIONS_DIR); git ls-files --others --exclude-standard -- $(MIGRATIONS_DIR); } | sort -u); \
	if [ -z "$$changed" ]; then echo "migrate-check-diff: no migration changed; skipped"; exit 0; fi; \
	echo "migrate-check-diff: $$(echo $$changed | wc -w | tr -d ' ') migration file(s) changed"; \
	$(MAKE) --no-print-directory migrate-check

## verify-static: the static checks that read source and no coverage profile.
##
## golangci-lint refuses to start while another instance is running ("parallel
## golangci-lint is running", exit 3), so `lint` and `bench-lint` cannot be
## scheduled side by side. `lint` itself runs in verify's serial preamble,
## before the lanes, so bench-lint here runs after it, cold, in two seconds.
## They are chained rather than made dependent on each other, which would make
## a standalone `make bench-lint` pay for the main module's two-minute lint.
##
## security (gosec + govulncheck + osv-scanner) and the whole-tree semgrep follow it. They
## used to run in verify-go after the full race unit run, so a gosec finding
## failed verify fifteen minutes in with every test lane green (#2053); here
## they start with the other lanes and report in the first minutes.
verify-static:
	@echo "[lane start $$(date +%T)] verify-static"
	@$(MAKE) --no-print-directory bench-lint
	@$(MAKE) --no-print-directory security
	@$(MAKE) --no-print-directory semgrep
	@echo "[lane done  $$(date +%T)] verify-static"

## verify-docker: everything that wants the Docker daemon, and nothing else.
verify-docker:
	@echo "[lane start $$(date +%T)] verify-docker"
	@$(MAKE) --no-print-directory migrate-check
	@$(MAKE) --no-print-directory test-realdb
	@echo "[lane done  $$(date +%T)] verify-docker"

## verify-ui: the frontend steps, then the release build that rebuilds the UI
## from scratch and must not overlap them. schedule-lane-ui is frontend-test
## with the changed test files repeated beside it.
verify-ui:
	@echo "[lane start $$(date +%T)] verify-ui"
	@$(MAKE) --no-print-directory schedule-lane-ui
	@$(MAKE) --no-print-directory frontend-e2e
	@$(MAKE) --no-print-directory release-check
	@echo "[lane done  $$(date +%T)] verify-ui"

## docs-serve: Serve documentation locally, with the pinned mkdocs docs-build installs
docs-serve: docs-build
	@echo "Serving documentation at http://localhost:8000..."
	$(DOCS_VENV)/bin/mkdocs serve

## help: Show this help message
help:
	@echo "mcp-data-platform Makefile"
	@echo ""
	@echo "Usage: make [target]"
	@echo ""
	@echo "Targets:"
	@grep -E '^## ' $(MAKEFILE_LIST) | sed 's/## /  /'

# =============================================================================
# Frontend Targets (unified portal UI)
# =============================================================================

## frontend-install: Install UI dependencies
frontend-install:
	@echo "Installing UI dependencies..."
	cd $(UI_DIR) && npm ci
	@echo "UI dependencies installed."

## frontend-build-content-viewer: Build the public share viewer (code-split JS + its own purged CSS)
frontend-build-content-viewer: frontend-install
	@$(MAKE) --no-print-directory content-viewer-embed

## frontend-build: Build and embed both frontends — the portal SPA and the public share viewer
frontend-build: frontend-install
	@echo "Building SPA..."
	cd $(UI_DIR) && npm run build
	@echo "Copying SPA dist to embed directory..."
	@rm -rf $(UI_EMBED_DIR)/*
	@cp -r $(UI_DIR)/dist/* $(UI_EMBED_DIR)/
	@rm -f $(UI_EMBED_DIR)/mockServiceWorker.js
	@echo "SPA built and embedded."
	@$(MAKE) --no-print-directory content-viewer-embed
	@echo "Frontend build complete."

## content-viewer-embed: Build the share viewer's chunks, then its stylesheet, then embed both.
## The order is load-bearing: content-viewer.css declares the emitted chunks as
## its only Tailwind source (see ui/src/content-viewer.css), so compiling it
## before the JS exists yields a stylesheet with no utilities in it.
content-viewer-embed:
	@echo "Building content viewer chunks..."
	cd $(UI_DIR) && npx vite build --config vite.content-viewer.config.ts
	@echo "Building content viewer stylesheet..."
	cd $(UI_DIR) && npx vite build --config vite.content-viewer-css.config.ts
	@# Chunk filenames carry a content hash, so a stale build's files would
	@# otherwise pile up in the embedded directory forever.
	@find $(CV_EMBED_DIR) -not -name '.gitkeep' -not -path $(CV_EMBED_DIR) -delete 2>/dev/null || true
	@mkdir -p $(CV_EMBED_DIR)
	@cp -r $(UI_DIR)/dist-content-viewer/. $(CV_EMBED_DIR)/
	@cp $(UI_DIR)/dist-content-viewer-css/content-viewer.css $(CV_EMBED_DIR)/
	@echo "Content viewer built and embedded."

## frontend-dev: Run UI dev server (hot reload)
frontend-dev:
	cd $(UI_DIR) && npm run dev

## frontend-mock: Run UI dev server with mock data (no backend needed)
frontend-mock:
	cd $(UI_DIR) && VITE_MSW=true npm run dev

## frontend-test: Run UI tests
frontend-test:
	cd $(UI_DIR) && npm run test

## frontend-lint: Run the UI complexity/coupling lint gate (#816, mirrors CI's frontend job lint step)
frontend-lint:
	cd $(UI_DIR) && npm run lint

## frontend-e2e: Run the interactive Playwright suite against the MSW-mocked dev server (mirrors CI's frontend-e2e job)
frontend-e2e:
	@# The suite reuses whatever is on its port, and it cannot tell an MSW
	@# server from any other Vite there (see e2e/interactive/playwright.config.ts).
	@# A `make dev` left running is one WITHOUT VITE_MSW, so on :5173 the suite
	@# would bind to the live backend and fail all 213 cases at sign-in.
	@#
	@# So the port is checked here. The marker is the flag main.tsx reads, which
	@# Vite inlines into the source it serves: an MSW server answers with
	@# "VITE_MSW": "true" in /portal/src/main.tsx and a plain one does not.
	@# mockServiceWorker.js is no use -- a static file both servers serve.
	@#
	@# A non-MSW server on the default port is a dev stack, and the suite runs
	@# beside it on the next free port rather than refusing (#1969):
	@# the acceptance suite runs against that same stack. An E2E_PORT set by
	@# hand is the caller's choice and is refused.
	@port=$${E2E_PORT:-5173}; \
	is_msw() { curl -sf -m 3 "http://localhost:$$1/portal/src/main.tsx" 2>/dev/null | grep -q '"VITE_MSW": *"true"'; }; \
	busy() { curl -s -o /dev/null -m 3 "http://localhost:$$1/" 2>/dev/null || lsof -nP -iTCP:$$1 -sTCP:LISTEN > /dev/null 2>&1; }; \
	if ! is_msw $$port && busy $$port; then \
		if [ -n "$$E2E_PORT" ]; then \
			echo "FAIL frontend-e2e: :$$port (E2E_PORT) is serving something that is NOT the MSW dev server." >&2; \
			echo "  The suite reuses whatever is on that port, so it would fail every case at sign-in. Choose a free port." >&2; \
			exit 1; \
		fi; \
		next=5199; while busy $$next; do next=$$((next + 1)); done; \
		echo "frontend-e2e: :$$port serves a dev server that is not the MSW one (a 'make dev'); running the suite on :$$next beside it."; \
		port=$$next; \
	fi; \
	cd $(UI_DIR) && npx playwright install chromium && E2E_PORT=$$port npm run test:e2e

## frontend-e2e-public-viewer: Run the public share viewer suite against a live stack (needs `make dev`; the E2E Nightly runs it, verify does not)
frontend-e2e-public-viewer:
	@echo "Public viewer suite needs a running stack (make dev) — the page, its"
	@echo "content-viewer bundle and its CSP are served by the Go binary."
	@if [ -f dev/.dev-ports.env ]; then . ./dev/.dev-ports.env; fi; \
	cd $(UI_DIR) && npx playwright install chromium && \
		PUBLIC_VIEWER_BASE_URL=$${PUBLIC_VIEWER_BASE_URL:-http://localhost:$${DEV_API_PORT:-8080}} \
		npm run test:public-viewer

## build-with-ui: Build Go binary with embedded UI
build-with-ui: frontend-build build

# =============================================================================
# E2E Testing Targets
# =============================================================================

# Cleared DOCKER_DEFAULT_PLATFORM (see DEV_COMPOSE below) so the local E2E stack
# uses the host's native platform for multi-arch images like pgvector.
E2E_COMPOSE := DOCKER_DEFAULT_PLATFORM= docker compose -f docker-compose.e2e.yml

## e2e-up: Start E2E test environment (PostgreSQL, Trino, SeaweedFS)
e2e-up:
	@echo "Starting E2E test environment..."
	$(E2E_COMPOSE) up -d postgres trino seaweedfs
	@echo "Waiting for services to be healthy..."
	@./scripts/wait-for-services.sh
	@echo "Running setup containers..."
	$(E2E_COMPOSE) up seaweedfs-setup trino-setup
	@echo "E2E environment is ready!"

## e2e-down: Stop E2E test environment
e2e-down:
	@echo "Stopping E2E test environment..."
	$(E2E_COMPOSE) down -v
	@echo "E2E environment stopped."

## e2e-test: Run E2E tests (requires services running)
e2e-test:
	@echo "Running E2E tests..."
	$(GOTEST) -v -race -tags=integration ./test/e2e/...
	@echo "E2E tests complete."

## e2e: Start the E2E environment and print the next steps (test, down)
e2e: e2e-up
	@echo ""
	@echo "Run the E2E tests, then stop the environment:"
	@echo "  make e2e-test"
	@echo "  make e2e-down"

## e2e-logs: Show E2E service logs
e2e-logs:
	$(E2E_COMPOSE) logs -f

## e2e-clean: Remove all E2E artifacts and volumes
e2e-clean: e2e-down
	@echo "Cleaning E2E artifacts..."
	@docker volume rm -f mcp-data-platform_postgres_data mcp-data-platform_seaweedfs_data 2>/dev/null || true
	@echo "E2E cleanup complete."

# =============================================================================
# Local Dev Environment (ACME Corporation)
# =============================================================================

# Clear DOCKER_DEFAULT_PLATFORM for the local dev stack: a developer who exports
# it as linux/amd64 (to build cluster images) would otherwise force the amd64
# variant of multi-arch images like pgvector/pgvector:pg16, which fails on an
# arm64 host whose cached image is arm64 ("platform does not match"). An empty
# value lets Docker pick the host's native platform, so this works on both
# arm64 and amd64 machines.
DEV_COMPOSE := DOCKER_DEFAULT_PLATFORM= docker compose -f dev/docker-compose.yml

## dev-up: Start ACME dev environment (PostgreSQL)
dev-up:
	@echo "Starting ACME dev environment..."
	$(DEV_COMPOSE) up -d
	@echo "Waiting for PostgreSQL to be healthy..."
	@for i in 1 2 3 4 5 6 7 8 9 10; do \
		if docker exec acme-dev-postgres pg_isready -U platform -d mcp_platform -q 2>/dev/null; then \
			echo "PostgreSQL is ready."; \
			break; \
		fi; \
		if [ $$i -eq 10 ]; then echo "ERROR: PostgreSQL failed to start"; exit 1; fi; \
		sleep 1; \
	done
	@echo ""
	@echo "=== ACME Dev Environment Ready ==="
	@echo ""
	@echo "Start the Go server:"
	@echo "  go run ./cmd/mcp-data-platform --config dev/platform.yaml"
	@echo ""
	@echo "(Optional) Seed historical data:"
	@echo "  psql -h localhost -U platform -d mcp_platform -f dev/seed.sql"
	@echo ""
	@echo "Start the portal UI:"
	@echo "  cd ui && npm run dev"
	@echo ""
	@echo "Or use MSW mode (no backend needed):"
	@echo "  cd ui && VITE_MSW=true npm run dev"
	@echo ""
	@echo "API Key: acme-dev-key-2024"
	@echo ""

## dev-stop: Stop ACME dev environment, KEEPING its data
## This is the one to use to free the ports -- for `make verify`, which needs
## 5173, or to get out of the way. The containers stop and the volumes stay, so
## the database and the blob store survive and the next `make dev` comes back to
## the stack you left: seeded rows, uploaded files, and captured thumbnails.
##
## Use dev-down only to deliberately reset. A thumbnail lives in Postgres and
## SeaweedFS, both of which are volumes, so `down -v` throws away every capture
## the portal has made and the queue starts the whole library again from zero.
dev-stop:
	@echo "Stopping ACME dev environment (keeping volumes)..."
	$(DEV_COMPOSE) --profile replicas stop
	$(MAKE) --no-print-directory dev-kill-hosts
	@echo "ACME dev environment stopped. Data kept; 'make dev' resumes it."

## dev-down: Stop ACME dev environment and DELETE its data (volumes)
## Destructive: removes the Postgres and SeaweedFS volumes, so seeded rows,
## uploaded blobs and every captured thumbnail go with them. To free the ports
## without losing any of that, use `make dev-stop`.
dev-down:
	@echo "Stopping ACME dev environment and REMOVING its volumes (data will be lost)..."
	$(DEV_COMPOSE) --profile replicas down -v
	$(MAKE) --no-print-directory dev-kill-hosts
	@echo "ACME dev environment stopped and its data removed."

## dev-kill-hosts: Kill the host-side dev processes (internal; used by dev-stop/dev-down)
## Docker being clean is not enough: dev/start.sh also runs air, vite and the
## MCP mock on the host, and its trap misses them when the script was
## backgrounded and the parent shell exited. Left behind, they hold 5173 and
## 9180 and the next `make dev` fails its port pre-flight.
dev-kill-hosts:
	@pkill -f "build/air/mcp-data-platform" 2>/dev/null || true
	@pkill -f "build/air-b/mcp-data-platform" 2>/dev/null || true
	@pkill -f "air -c dev/.air.toml" 2>/dev/null || true
	@pkill -f "ui/node_modules/.bin/vite" 2>/dev/null || true
	@pkill -f "@esbuild/.*/bin/esbuild --service" 2>/dev/null || true
	@pkill -f "go run ./cmd/dev-mcp-mock" 2>/dev/null || true
	@pkill -f "/dev-mcp-mock$$" 2>/dev/null || true

## dev: Start full dev environment with hot-reload (Docker + Go + Vite)
## Runs pre-flight checks (Docker, air, ports), starts services sequentially,
## waits for health, seeds data on first run, and reports clear status.
dev:
	@bash dev/start.sh

## dev-info: Print the dev login (Portal URL, API key, sign-in users)
## Handy when `make dev`'s startup banner has scrolled out of view.
dev-info:
	@bash dev/info.sh

## mock-check: Verify MSW mocks conform to Swagger spec types
mock-check: swagger
	@echo "Generating TypeScript types from Swagger spec..."
	cd $(UI_DIR) && npm run generate-api-types
	@echo "Type-checking mocks against generated types..."
	cd $(UI_DIR) && npx tsc --noEmit
	@echo "Running mock conformance tests..."
	cd $(UI_DIR) && npx vitest run src/mocks/conformance.test.ts
	@echo "Mock conformance check passed."

## preview-apps: Serve MCP apps locally at http://localhost:8000/test-harness.html (no server needed)
preview-apps:
	@echo "→ Open http://localhost:8000/test-harness.html"
	@cd apps && python3 -m http.server 8000 --bind 127.0.0.1

## preview-platform-info: Preview platform_info app with data from a real config file.
## Accepts a Kubernetes ConfigMap YAML or direct platform YAML.
## Usage: make preview-platform-info CONFIG=/path/to/config.yaml
## Requires Python 3 + PyYAML: pip3 install pyyaml
preview-platform-info:
	@if [ -z "$(CONFIG)" ]; then \
		echo "Usage: make preview-platform-info CONFIG=/path/to/config.yaml"; \
		exit 1; \
	fi
	@echo "→ Extracting preview data from $(CONFIG)"
	@python3 scripts/extract-preview-data.py "$(CONFIG)" apps/preview-data.json
	@$(MAKE) preview-apps

# =============================================================================
# Load Testing (issue #921)
# =============================================================================
#
# The load harness lives in test/load (a separate Go module, kept out of the
# root coverage/test/lint denominator). It drives named workloads against a
# running platform over the MCP protocol and REST surfaces and publishes numbers
# in docs/reference/tuning-and-scaling.md.
#
# Like `mutate`, load testing is DELIBERATELY NOT part of `make verify`: it
# stands up Docker services and a real server binary and runs for tens of
# seconds to an hour per scenario — far too slow and heavy for a per-commit
# gate. Do NOT add load-* to the `verify` target. Run it on demand, locally or
# via the workflow_dispatch load.yml workflow.

# LOAD_KEY is the admin API key the harness authenticates with. Override for a
# non-default deployment. LOAD_CONFIG points at the platform config for the run.
LOAD_KEY ?= load-admin-key
LOAD_CONFIG ?= test/load/config/platform.load.yaml
LOAD_ADDR ?= :8099
LOAD_METRICS_ADDR ?= :9091
LOAD_PPROF_ADDR ?= :6060
LOAD_URL ?= http://localhost:8099
LOAD_PID := build/mcp-data-platform-load.pid
LOAD_LOG := build/mcp-data-platform-load.log

## load-up: Start the compose stack and a release-built platform for load tests
load-up: e2e-up
	@echo "Building release-style platform binary (no -race)..."
	@mkdir -p $(BUILD_DIR)
	$(GOBUILD) $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-load $(CMD_DIR)
	@echo "Building loadgen..."
	@cd test/load && $(GO) build -o ../../$(BUILD_DIR)/loadgen ./loadgen
	@echo "Starting platform on $(LOAD_ADDR) (metrics $(LOAD_METRICS_ADDR), pprof $(LOAD_PPROF_ADDR))..."
	@API_KEY_ADMIN=$(LOAD_KEY) LOG_LEVEL=info \
		OTEL_METRICS_ADDR=$(LOAD_METRICS_ADDR) PPROF_ADDR=$(LOAD_PPROF_ADDR) \
		OAUTH_RL_ENABLED=$(OAUTH_RL_ENABLED) AUDIT_DELIVERY=$(AUDIT_DELIVERY) \
		$(BUILD_DIR)/$(BINARY_NAME)-load --config $(LOAD_CONFIG) --transport http --address $(LOAD_ADDR) \
		> $(LOAD_LOG) 2>&1 & echo $$! > $(LOAD_PID)
	@echo "Waiting for readiness on $(LOAD_URL)/readyz ..."
	@for i in $$(seq 1 30); do \
		if curl -fsS $(LOAD_URL)/readyz >/dev/null 2>&1; then echo "Platform ready (pid $$(cat $(LOAD_PID)))."; exit 0; fi; \
		sleep 1; \
	done; \
	echo "ERROR: platform did not become ready; see $(LOAD_LOG)"; tail -20 $(LOAD_LOG); exit 1

## load-run: Run one load scenario (SCENARIO=<name>; see loadgen -list)
## Optional: CONCURRENCY=, DURATION=, WARMUP=, RATE=, OUT= override defaults.
load-run:
	@if [ -z "$(SCENARIO)" ]; then echo "Usage: make load-run SCENARIO=<name> (see: $(BUILD_DIR)/loadgen -list)"; exit 1; fi
	@mkdir -p build/load-reports
	$(BUILD_DIR)/loadgen \
		-scenario $(SCENARIO) \
		-url $(LOAD_URL) \
		-metrics-url http://localhost$(LOAD_METRICS_ADDR)/metrics \
		-pprof-url http://localhost$(LOAD_PPROF_ADDR) \
		-credential $(LOAD_KEY) \
		-release-build \
		-profile-dir build/load-reports/profiles \
		-out build/load-reports/report-$(SCENARIO).json \
		$(if $(CONCURRENCY),-concurrency $(CONCURRENCY),) \
		$(if $(DURATION),-duration $(DURATION),) \
		$(if $(WARMUP),-warmup $(WARMUP),) \
		$(if $(RATE),-rate $(RATE),)

## load-down: Stop the load platform and the compose stack
load-down:
	@if [ -f $(LOAD_PID) ]; then \
		echo "Stopping platform (pid $$(cat $(LOAD_PID)))..."; \
		kill $$(cat $(LOAD_PID)) 2>/dev/null || true; \
		rm -f $(LOAD_PID); \
	fi
	@$(MAKE) e2e-down

## load-test: Build, vet, lint, and unit-test the harness module itself
load-test:
	@echo "Testing the load harness module..."
	@cd test/load && $(GO) build ./... && $(GO) vet ./... && $(GO) test ./...

# =============================================================================
# Agent-Effectiveness Benchmark (issue #930, phase 1: #942)
# =============================================================================
#
# The benchmark harness lives in bench/ (a separate Go module, kept out of the
# root coverage/test/lint denominator, like test/load). It ablates the PLATFORM
# (arms a0/a2 as config profiles) while holding the model, prompt scaffold,
# seed data, and task set constant, and reads efficiency metrics back from the
# platform's own audit API.
#
# Like `mutate` and `load-*`, benchmarking is DELIBERATELY NOT part of
# `make verify`: it stands up Docker services, a real server binary, and (for
# real runs) a model API. Do NOT add bench-* to the `verify` target.
#
# Arms (config profiles selected by BENCH_ARM):
#   a0  baseline — raw tools, no enrichment, no search
#   a1  enrichment — a0 plus semantic cross-enrichment from the platform catalog
#   a2  knowledge — a1 plus search, the search-first gate, knowledge pages
#   a3  lifecycle — a2 plus memory/insight + apply_knowledge
# bench-up seeds the platform catalog with the bench curation
# (bench/seed/postgres/catalog.sql), or with the undocumented datasets alone
# under BENCH_SEED_PAGES=0, the cold-start empty baseline.

# BENCH_ARM selects the platform config profile; BENCH_KEY is the admin API key.
BENCH_ARM ?= a0
BENCH_KEY ?= bench-admin-key
BENCH_CONFIG ?= bench/config/platform.bench.$(BENCH_ARM).yaml
BENCH_ADDR ?= :8098
BENCH_METRICS_ADDR ?= :9092
BENCH_URL ?= http://localhost:8098
BENCH_PID := build/mcp-data-platform-bench.pid
BENCH_LOG := build/mcp-data-platform-bench.log
BENCH_COMPOSE := DOCKER_DEFAULT_PLATFORM= docker compose -f docker-compose.e2e.yml

## bench-gen: Regenerate seed artifacts, the task set, and the S5 protocols from the fixed seed
bench-gen:
	@cd bench && $(GO) run ./seedgen -seed-dir seed -tasks-dir tasks -protocols-dir protocols -curriculum-dir curriculum

# --- API-connection architecture study (issue #1027) ---------------------
# Arms are config profiles (BENCH_ARM=b0|b1-lex|b1-hyb); the catalog tier
# is a run parameter (BENCH_TIER=t0|t1|t2). bench-api-up starts Postgres,
# the fixture service (apisvc), the per-endpoint MCP server (epmcp, b0
# only), and the platform, then registers the fixture through the admin
# REST API (apisetup). b1-hyb additionally waits for the embedding index
# to cover every operation (requires ollama serve + nomic-embed-text).
BENCH_TIER ?= t0
BENCH_APISVC_ADDR ?= :8110
BENCH_APISVC_URL ?= http://127.0.0.1:8110
BENCH_EPMCP_ADDR ?= :8111
BENCH_EPMCP_URL ?= http://127.0.0.1:8111
BENCH_APISVC_KEY ?= bench-fixture-key
BENCH_APISVC_PID := build/bench-apisvc.pid
BENCH_APISVC_LOG := build/bench-apisvc.log
BENCH_EPMCP_PID := build/bench-epmcp.pid
BENCH_EPMCP_LOG := build/bench-epmcp.log
BENCH_EMBED_WAIT ?= 60m
# The b* arms use their own database (mcp_bench_api) so bench state and
# migration version never collide with a dev/e2e mcp_platform database
# migrated by another branch. Created idempotently at bench-api-up.
BENCH_PG_CONTAINER ?= e2e-postgres

## bench-api-gen: Regenerate the API study's specs and task set from the fixed seeds
bench-api-gen:
	@cd bench && $(GO) run ./apigen -specs-dir specs -tasks-dir tasks-api

## bench-api-up: Start Postgres + fixture service (+epmcp for b0) + platform, then register fixtures (BENCH_ARM=b0|b1-lex|b1-hyb|b2, BENCH_TIER=t0|t1|t2). b2 (code mode) starts only the fixture service: no platform, no MCP.
bench-api-up:
	@case "$(BENCH_ARM)" in b0|b1-lex|b1-hyb|b2) ;; \
		*) echo "ERROR: bench-api-up needs BENCH_ARM=b0|b1-lex|b1-hyb|b2 (got '$(BENCH_ARM)')"; exit 1 ;; esac
	@if [ "$(BENCH_PG)" = "skip" ]; then \
		echo "Using external Postgres on 5432 (BENCH_PG=skip)..."; \
	else \
		echo "Starting Postgres..."; \
		$(BENCH_COMPOSE) up -d postgres; \
		for i in $$(seq 1 30); do \
			if docker exec e2e-postgres pg_isready -U platform -d mcp_platform -q 2>/dev/null; then break; fi; \
			sleep 1; \
		done; \
		docker exec e2e-postgres pg_isready -U platform -d mcp_platform -q || { echo "ERROR: Postgres not ready"; exit 1; }; \
	fi
	@docker exec $(BENCH_PG_CONTAINER) psql -U platform -d postgres -tc \
		"SELECT 1 FROM pg_database WHERE datname='mcp_bench_api'" 2>/dev/null | grep -q 1 \
		|| docker exec $(BENCH_PG_CONTAINER) psql -U platform -d postgres -c "CREATE DATABASE mcp_bench_api OWNER platform"
	@echo "Building binaries..."
	@mkdir -p $(BUILD_DIR)
	$(GOBUILD) $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-bench $(CMD_DIR)
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/bench-apisvc ./apisvc \
		&& $(GO) build -o ../$(BUILD_DIR)/bench-epmcp ./epmcp \
		&& $(GO) build -o ../$(BUILD_DIR)/bench-apisetup ./apisetup \
		&& $(GO) build -o ../$(BUILD_DIR)/benchrun ./benchrun
	@for pid in $(BENCH_APISVC_PID) $(BENCH_EPMCP_PID) $(BENCH_PID); do \
		if [ -f $$pid ]; then \
			kill $$(cat $$pid) 2>/dev/null || true; \
			while kill -0 $$(cat $$pid) 2>/dev/null; do sleep 1; done; \
			rm -f $$pid; \
		fi; \
	done
	@echo "Starting fixture service on $(BENCH_APISVC_ADDR)..."
	@$(BUILD_DIR)/bench-apisvc -addr $(BENCH_APISVC_ADDR) -api-key $(BENCH_APISVC_KEY) \
		> $(BENCH_APISVC_LOG) 2>&1 & echo $$! > $(BENCH_APISVC_PID)
	@for i in $$(seq 1 15); do \
		if curl -fsS -H "X-API-Key: $(BENCH_APISVC_KEY)" $(BENCH_APISVC_URL)/_bench/requests >/dev/null 2>&1; then break; fi; \
		sleep 1; \
	done; \
	curl -fsS -H "X-API-Key: $(BENCH_APISVC_KEY)" $(BENCH_APISVC_URL)/_bench/requests >/dev/null 2>&1 \
		|| { echo "ERROR: fixture service not ready; see $(BENCH_APISVC_LOG)"; tail -5 $(BENCH_APISVC_LOG); exit 1; }
	@if [ "$(BENCH_ARM)" = "b0" ]; then \
		echo "Starting per-endpoint MCP server ($(BENCH_TIER)) on $(BENCH_EPMCP_ADDR)..."; \
		$(BUILD_DIR)/bench-epmcp -addr $(BENCH_EPMCP_ADDR) -spec bench/specs/$(BENCH_TIER).json \
			-target $(BENCH_APISVC_URL) -api-key $(BENCH_APISVC_KEY) \
			> $(BENCH_EPMCP_LOG) 2>&1 & echo $$! > $(BENCH_EPMCP_PID); \
		for i in $$(seq 1 15); do \
			code=$$(curl -s -o /dev/null -w "%{http_code}" $(BENCH_EPMCP_URL) 2>/dev/null); \
			if [ "$$code" != "000" ]; then break; fi; \
			sleep 1; \
		done; \
		kill -0 $$(cat $(BENCH_EPMCP_PID)) 2>/dev/null \
			|| { echo "ERROR: epmcp exited; see $(BENCH_EPMCP_LOG)"; tail -5 $(BENCH_EPMCP_LOG); exit 1; }; \
	fi
	@if [ "$(BENCH_ARM)" = "b2" ]; then \
		echo "Code mode: no platform, no MCP — fixture service only."; \
	else \
		if curl -fsS $(BENCH_URL)/readyz >/dev/null 2>&1; then \
			echo "ERROR: something else is already serving $(BENCH_URL); run 'make bench-api-down' first"; exit 1; fi; \
		echo "Starting platform ($(BENCH_CONFIG)) on $(BENCH_ADDR)..."; \
		API_KEY_ADMIN=$(BENCH_KEY) LOG_LEVEL=info OTEL_METRICS_ADDR=$(BENCH_METRICS_ADDR) \
			$(BUILD_DIR)/$(BINARY_NAME)-bench --config $(BENCH_CONFIG) --transport http --address $(BENCH_ADDR) \
			> $(BENCH_LOG) 2>&1 & echo $$! > $(BENCH_PID); \
		for i in $$(seq 1 30); do \
			if curl -fsS $(BENCH_URL)/readyz >/dev/null 2>&1; then break; fi; \
			sleep 1; \
		done; \
		curl -fsS $(BENCH_URL)/readyz >/dev/null 2>&1 \
			|| { echo "ERROR: platform did not become ready; see $(BENCH_LOG)"; tail -20 $(BENCH_LOG); exit 1; }; \
		kill -0 $$(cat $(BENCH_PID)) 2>/dev/null \
			|| { echo "ERROR: bench platform exited after start; see $(BENCH_LOG)"; tail -20 $(BENCH_LOG); exit 1; }; \
		echo "Registering fixtures (arm $(BENCH_ARM), tier $(BENCH_TIER))..."; \
		case "$(BENCH_ARM)" in \
			b0) $(BUILD_DIR)/bench-apisetup -mode b0 -url $(BENCH_URL) -credential $(BENCH_KEY) \
				-epmcp $(BENCH_EPMCP_URL) ;; \
			b1-lex) $(BUILD_DIR)/bench-apisetup -mode b1 -url $(BENCH_URL) -credential $(BENCH_KEY) \
				-spec bench/specs/$(BENCH_TIER).json -fixture $(BENCH_APISVC_URL) -fixture-key $(BENCH_APISVC_KEY) ;; \
			b1-hyb) $(BUILD_DIR)/bench-apisetup -mode b1 -url $(BENCH_URL) -credential $(BENCH_KEY) \
				-spec bench/specs/$(BENCH_TIER).json -fixture $(BENCH_APISVC_URL) -fixture-key $(BENCH_APISVC_KEY) \
				-wait-embed $(BENCH_EMBED_WAIT) ;; \
		esac; \
	fi
	@echo "API study stack ready (arm $(BENCH_ARM), tier $(BENCH_TIER))."

## bench-api-run: Run the API-connection study benchmark against the running b* stack (BENCH_ARM, BENCH_TIER; LLM=, SCRIPT=, K=, MODEL=, SUITE=)
bench-api-run:
	@mkdir -p build/bench-results
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/benchrun ./benchrun
	@dir="build/bench-results/api-$(BENCH_ARM)-$(BENCH_TIER)-$$(date +%Y%m%d-%H%M%S)"; \
	mkdir -p $$dir; \
	echo "Results dir: $$dir"; \
	$(BUILD_DIR)/benchrun \
		-url $(BENCH_URL) \
		-credential $(BENCH_KEY) \
		-arm $(BENCH_ARM) \
		-tier $(BENCH_TIER) \
		-tasks bench/tasks-api \
		-fixture-url $(BENCH_APISVC_URL) \
		-fixture-key $(BENCH_APISVC_KEY) \
		-identity-keys 150 \
		-git-commit $$(git rev-parse HEAD) \
		-out $$dir/results.json \
		$(if $(filter b2,$(BENCH_ARM)),-code-spec bench/specs/$(BENCH_TIER).json,) \
		$(if $(LLM),-llm $(LLM),) \
		$(if $(SCRIPT),-script $(SCRIPT),) \
		$(if $(SUITE),-suite $(SUITE),) \
		$(if $(K),-k $(K),) \
		$(if $(MODEL),-model $(MODEL),)

## bench-api-smoke: Scripted (no-API-key) end-to-end smoke against the running b1 stack
bench-api-smoke:
	@$(MAKE) bench-api-run LLM=scripted SCRIPT=bench/tasks-api/scripted-smoke.json K=1

# --- Perishable-knowledge study (issue #1054) ----------------------------
# One arm (bench/config/platform.bench.pk.yaml), one spec (bench/specs/pk.json),
# and a fixture service serving the perishable surface. The world a cell starts
# in is BENCH_PK_WORLD; the harness changes it between sessions through the
# fixture's own control plane, not through a restart. Its own database
# (mcp_bench_pk) keeps study state off the #1027 and dev databases.
BENCH_PK_APISVC_ADDR ?= :8112
BENCH_PK_APISVC_URL ?= http://127.0.0.1:8112
BENCH_PK_APISVC_KEY ?= bench-pk-fixture-key
BENCH_PK_WORLD ?= monitors-0
BENCH_PK_CONFIG := bench/config/platform.bench.pk.yaml
BENCH_PK_APISVC_PID := build/bench-pk-apisvc.pid
BENCH_PK_APISVC_LOG := build/bench-pk-apisvc.log

## bench-pk-up: Start Postgres + the perishable fixture + platform, then register the fixture (#1054; BENCH_PK_WORLD=)
bench-pk-up:
	@if [ "$(BENCH_PG)" = "skip" ]; then \
		echo "Using external Postgres on 5432 (BENCH_PG=skip)..."; \
	else \
		echo "Starting Postgres..."; \
		$(BENCH_COMPOSE) up -d postgres; \
		for i in $$(seq 1 30); do \
			if docker exec e2e-postgres pg_isready -U platform -d mcp_platform -q 2>/dev/null; then break; fi; \
			sleep 1; \
		done; \
		docker exec e2e-postgres pg_isready -U platform -d mcp_platform -q || { echo "ERROR: Postgres not ready"; exit 1; }; \
	fi
	@docker exec $(BENCH_PG_CONTAINER) psql -U platform -d postgres -tc \
		"SELECT 1 FROM pg_database WHERE datname='mcp_bench_pk'" 2>/dev/null | grep -q 1 \
		|| docker exec $(BENCH_PG_CONTAINER) psql -U platform -d postgres -c "CREATE DATABASE mcp_bench_pk OWNER platform"
	@echo "Building binaries..."
	@mkdir -p $(BUILD_DIR)
	$(GOBUILD) $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-bench $(CMD_DIR)
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/bench-apisvc ./apisvc \
		&& $(GO) build -o ../$(BUILD_DIR)/bench-apisetup ./apisetup \
		&& $(GO) build -o ../$(BUILD_DIR)/benchrun ./benchrun
	@for pid in $(BENCH_PK_APISVC_PID) $(BENCH_PID); do \
		if [ -f $$pid ]; then \
			kill $$(cat $$pid) 2>/dev/null || true; \
			while kill -0 $$(cat $$pid) 2>/dev/null; do sleep 1; done; \
			rm -f $$pid; \
		fi; \
	done
	@echo "Starting perishable fixture service on $(BENCH_PK_APISVC_ADDR) (world $(BENCH_PK_WORLD))..."
	@$(BUILD_DIR)/bench-apisvc -addr $(BENCH_PK_APISVC_ADDR) -api-key $(BENCH_PK_APISVC_KEY) \
		-surface perishable -world $(BENCH_PK_WORLD) \
		> $(BENCH_PK_APISVC_LOG) 2>&1 & echo $$! > $(BENCH_PK_APISVC_PID)
	@for i in $$(seq 1 15); do \
		if curl -fsS -H "X-API-Key: $(BENCH_PK_APISVC_KEY)" $(BENCH_PK_APISVC_URL)/_bench/world >/dev/null 2>&1; then break; fi; \
		sleep 1; \
	done; \
	curl -fsS -H "X-API-Key: $(BENCH_PK_APISVC_KEY)" $(BENCH_PK_APISVC_URL)/_bench/world >/dev/null 2>&1 \
		|| { echo "ERROR: fixture service not ready; see $(BENCH_PK_APISVC_LOG)"; tail -5 $(BENCH_PK_APISVC_LOG); exit 1; }
	@if curl -fsS $(BENCH_URL)/readyz >/dev/null 2>&1; then \
		echo "ERROR: something else is already serving $(BENCH_URL); run 'make bench-pk-down' first"; exit 1; fi
	@echo "Starting platform ($(BENCH_PK_CONFIG)) on $(BENCH_ADDR)..."
	@API_KEY_ADMIN=$(BENCH_KEY) LOG_LEVEL=info OTEL_METRICS_ADDR=$(BENCH_METRICS_ADDR) \
		$(BUILD_DIR)/$(BINARY_NAME)-bench --config $(BENCH_PK_CONFIG) --transport http --address $(BENCH_ADDR) \
		> $(BENCH_LOG) 2>&1 & echo $$! > $(BENCH_PID)
	@for i in $$(seq 1 30); do \
		if curl -fsS $(BENCH_URL)/readyz >/dev/null 2>&1; then break; fi; \
		sleep 1; \
	done; \
	curl -fsS $(BENCH_URL)/readyz >/dev/null 2>&1 \
		|| { echo "ERROR: platform did not become ready; see $(BENCH_LOG)"; tail -20 $(BENCH_LOG); exit 1; }
	@echo "Registering the perishable fixture..."
	@$(BUILD_DIR)/bench-apisetup -mode b1 -url $(BENCH_URL) -credential $(BENCH_KEY) \
		-spec bench/specs/pk.json -fixture $(BENCH_PK_APISVC_URL) -fixture-key $(BENCH_PK_APISVC_KEY)
	@echo "Perishable-knowledge stack ready (world $(BENCH_PK_WORLD))."

## bench-pk-corpus: Run the capture-corpus episodes against the running pk stack (#1054 stage 1; REPLICATES=, MODEL=)
bench-pk-corpus:
	@mkdir -p build/bench-results
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/bench-pkcorpus ./pkcorpus
	@dir="build/bench-results/pk-corpus-$$(date +%Y%m%d-%H%M%S)"; \
	mkdir -p $$dir; \
	echo "Corpus dir: $$dir"; \
	$(BUILD_DIR)/bench-pkcorpus \
		-url $(BENCH_URL) \
		-credential $(BENCH_KEY) \
		-fixture-url $(BENCH_PK_APISVC_URL) \
		-fixture-key $(BENCH_PK_APISVC_KEY) \
		-identity-keys 150 \
		-git-commit $$(git rev-parse HEAD) \
		-out $$dir \
		$(if $(REPLICATES),-replicates $(REPLICATES),) \
		$(if $(MODEL),-model $(MODEL),)

## bench-pk-run: Run perishable-knowledge study cells against the running pk stack (#1054; CELLS=prerun, K=, MODEL=)
bench-pk-run:
	@mkdir -p build/bench-results
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/bench-pkrun ./pkrun
	@dir="build/bench-results/pk-$(if $(CELLS),$(CELLS),prerun)-$$(date +%Y%m%d-%H%M%S)"; \
	mkdir -p $$dir; \
	echo "Results dir: $$dir"; \
	$(BUILD_DIR)/bench-pkrun \
		-url $(BENCH_URL) \
		-credential $(BENCH_KEY) \
		-fixture-url $(BENCH_PK_APISVC_URL) \
		-fixture-key $(BENCH_PK_APISVC_KEY) \
		-identity-keys 150 \
		-git-commit $$(git rev-parse HEAD) \
		-out $$dir \
		$(if $(CELLS),-cells $(CELLS),) \
		$(if $(K),-k $(K),) \
		$(if $(MODEL),-model $(MODEL),)

## bench-pk-down: Stop the perishable-knowledge stack (platform, fixture service, compose)
bench-pk-down:
	@for pid in $(BENCH_PID) $(BENCH_PK_APISVC_PID); do \
		if [ -f $$pid ]; then \
			kill $$(cat $$pid) 2>/dev/null || true; \
			rm -f $$pid; \
		fi; \
	done
	@$(MAKE) e2e-down

# --- Graph-traversal premise probe (issue #1241) -------------------------
# One arm (bench/config/platform.bench.gt.yaml) and one seeded page corpus,
# planted through the platform's own knowledge-page API by bench/graphprobe.
# Its own database (mcp_bench_gt) keeps the corpus off every other study's
# stack. Needs `ollama serve` with nomic-embed-text: page content is embedded
# in chunks and search ranks a page by its best-matching chunk, so a run
# without the provider would be reading a lexical-only search.
BENCH_GT_CONFIG := bench/config/platform.bench.gt.yaml
BENCH_GT_PLANT := build/bench-results/graph-completion-plant.json
BENCH_GT_GATE := build/bench-results/graph-completion-gate.json
BENCH_GT_KEYS ?= 64

## bench-gt-up: Start Postgres + the platform on the graph-traversal probe arm (#1241)
bench-gt-up:
	@if [ "$(BENCH_PG)" = "skip" ]; then \
		echo "Using external Postgres on 5432 (BENCH_PG=skip)..."; \
	else \
		echo "Starting Postgres..."; \
		$(BENCH_COMPOSE) up -d postgres; \
		for i in $$(seq 1 30); do \
			if docker exec e2e-postgres pg_isready -U platform -d mcp_platform -q 2>/dev/null; then break; fi; \
			sleep 1; \
		done; \
		docker exec e2e-postgres pg_isready -U platform -d mcp_platform -q || { echo "ERROR: Postgres not ready"; exit 1; }; \
	fi
	@docker exec $(BENCH_PG_CONTAINER) psql -U platform -d postgres -tc \
		"SELECT 1 FROM pg_database WHERE datname='mcp_bench_gt'" 2>/dev/null | grep -q 1 \
		|| docker exec $(BENCH_PG_CONTAINER) psql -U platform -d postgres -c "CREATE DATABASE mcp_bench_gt OWNER platform"
	@echo "Building binaries..."
	@mkdir -p $(BUILD_DIR)
	$(GOBUILD) $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-bench $(CMD_DIR)
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/bench-graphprobe ./graphprobe
	@if [ -f $(BENCH_PID) ]; then \
		kill $$(cat $(BENCH_PID)) 2>/dev/null || true; \
		while kill -0 $$(cat $(BENCH_PID)) 2>/dev/null; do sleep 1; done; \
		rm -f $(BENCH_PID); \
	fi
	@if curl -fsS $(BENCH_URL)/readyz >/dev/null 2>&1; then \
		echo "ERROR: something else is already serving $(BENCH_URL); run 'make bench-gt-down' first"; exit 1; fi
	@echo "Starting platform ($(BENCH_GT_CONFIG)) on $(BENCH_ADDR)..."
	@API_KEY_ADMIN=$(BENCH_KEY) LOG_LEVEL=info OTEL_METRICS_ADDR=$(BENCH_METRICS_ADDR) \
		$(BUILD_DIR)/$(BINARY_NAME)-bench --config $(BENCH_GT_CONFIG) --transport http --address $(BENCH_ADDR) \
		> $(BENCH_LOG) 2>&1 & echo $$! > $(BENCH_PID)
	@for i in $$(seq 1 30); do \
		if curl -fsS $(BENCH_URL)/readyz >/dev/null 2>&1; then break; fi; \
		sleep 1; \
	done; \
	curl -fsS $(BENCH_URL)/readyz >/dev/null 2>&1 \
		|| { echo "ERROR: platform did not become ready; see $(BENCH_LOG)"; tail -20 $(BENCH_LOG); exit 1; }
	@echo "Graph-traversal probe stack ready."

## bench-gt-plant: Plant the page corpus through the platform's knowledge-page API (#1241; STRIP=1 for the stripped arm)
bench-gt-plant:
	@mkdir -p build/bench-results
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/bench-graphprobe ./graphprobe
	$(BUILD_DIR)/bench-graphprobe -mode plant -url $(BENCH_URL) -credential $(BENCH_KEY) -plant $(BENCH_GT_PLANT) \
		$(if $(STRIP),-strip,)

## bench-gt-reset: Delete the planted corpus so the other arm can be planted (#1241)
bench-gt-reset:
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/bench-graphprobe ./graphprobe
	$(BUILD_DIR)/bench-graphprobe -mode reset -url $(BENCH_URL) -credential $(BENCH_KEY) -plant $(BENCH_GT_PLANT)

## bench-gt-gate: Run the pre-stated sweep gate over search; non-zero on a leak (#1241)
bench-gt-gate:
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/bench-graphprobe ./graphprobe
	$(BUILD_DIR)/bench-graphprobe -mode gate -url $(BENCH_URL) -credential $(BENCH_KEY) \
		-plant $(BENCH_GT_PLANT) -gate $(BENCH_GT_GATE) -identity-keys $(BENCH_GT_KEYS)

## bench-gt-run: Run the completion cells into a fresh per-run dir under build/bench-results/ (#1241; K=, MODEL=, NOSEARCH=1)
bench-gt-run:
	@mkdir -p build/bench-results
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/bench-graphprobe ./graphprobe
	@arm=$$(grep -q '"stripped": true' $(BENCH_GT_PLANT) && echo stripped || echo graph); \
	search=$(if $(NOSEARCH),nosearch,search); \
	dir="build/bench-results/gc-$(if $(MODEL),$(MODEL),sonnet)-$$arm-$$search-$$(date +%Y%m%d-%H%M%S)"; \
	mkdir -p $$dir; \
	echo "Results dir: $$dir"; \
	$(BUILD_DIR)/bench-graphprobe -mode run \
		-url $(BENCH_URL) \
		-credential $(BENCH_KEY) \
		-plant $(BENCH_GT_PLANT) \
		-gate $(BENCH_GT_GATE) \
		-identity-keys $(BENCH_GT_KEYS) \
		-git-commit $$(git rev-parse HEAD) \
		-out $$dir \
		$(if $(NOSEARCH),-no-search,) \
		$(if $(K),-k $(K),) \
		$(if $(MODEL),-model $(MODEL),)

# --- Graph-completion study, stage 3 (issue #1250) ------------------------
# The deterministic study corpus at controlled scale, its authoring-time
# embedding certification, and the live sweep gate with the discontinuity
# requirement on. Reuses the gt stack (bench-gt-up / bench-gt-down) and its
# ollama requirement; certification talks to ollama directly and needs no
# stack at all.
#
# The default scale is the smallest CERTIFIABLE one: scale 50 is the study's
# within-enumeration-ceiling control, where certification is unsatisfiable by
# construction and both gates exit non-zero on purpose. Run it explicitly
# (BENCH_GS_SCALE=50) when recording that reading.
BENCH_GS_SCALE ?= 500

## bench-gs-certify: Offline embedding certification of the study corpus at SCALE (#1250; no stack needed, ollama required)
bench-gs-certify:
	@mkdir -p build/bench-results
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/bench-graphstudy ./graphstudy
	$(BUILD_DIR)/bench-graphstudy -mode certify -scale $(BENCH_GS_SCALE)

## bench-gs-plant: Generate and plant the study corpus at SCALE through the platform API (#1250; STRIP=1 for the stripped arm)
bench-gs-plant:
	@mkdir -p build/bench-results
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/bench-graphstudy ./graphstudy
	$(BUILD_DIR)/bench-graphstudy -mode plant -url $(BENCH_URL) -credential $(BENCH_KEY) \
		-scale $(BENCH_GS_SCALE) $(if $(STRIP),-strip,)

## bench-gs-gate: Live sweep gate over the planted study corpus, discontinuity requirement on (#1250)
bench-gs-gate:
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/bench-graphstudy ./graphstudy
	$(BUILD_DIR)/bench-graphstudy -mode gate -url $(BENCH_URL) -credential $(BENCH_KEY) \
		-scale $(BENCH_GS_SCALE) -identity-keys $(BENCH_GT_KEYS)

## bench-gs-run: Run the confirmatory cells into a fresh per-run dir under build/bench-results/ (#1251; K=, MODEL=, NOSEARCH=1)
bench-gs-run:
	@mkdir -p build/bench-results
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/bench-graphstudy ./graphstudy
	@test -f build/bench-results/graph-study-plant-$(BENCH_GS_SCALE).json || \
		{ echo "ERROR: no plant record for scale $(BENCH_GS_SCALE); run bench-gs-plant first"; exit 1; }
	@arm=$$(grep -q '"stripped": true' build/bench-results/graph-study-plant-$(BENCH_GS_SCALE).json && echo stripped || echo graph); \
	search=$(if $(NOSEARCH),nosearch,search); \
	git_commit=$$(git rev-parse HEAD); git diff --quiet HEAD || git_commit="$$git_commit-dirty"; \
	dir="build/bench-results/gs$(BENCH_GS_SCALE)-$(if $(MODEL),$(MODEL),opus)-$$arm-$$search-$$(date +%Y%m%d-%H%M%S)"; \
	mkdir -p $$dir; \
	echo "Results dir: $$dir"; \
	$(BUILD_DIR)/bench-graphstudy -mode run \
		-url $(BENCH_URL) \
		-credential $(BENCH_KEY) \
		-scale $(BENCH_GS_SCALE) \
		-identity-keys $(BENCH_GT_KEYS) \
		-git-commit $$git_commit \
		-out $$dir \
		$(if $(NOSEARCH),-no-search,) \
		$(if $(K),-k $(K),) \
		$(if $(MODEL),-model $(MODEL),)

## bench-gs-reset: Delete the planted study corpus so another scale or arm can go in (#1250)
bench-gs-reset:
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/bench-graphstudy ./graphstudy
	$(BUILD_DIR)/bench-graphstudy -mode reset -url $(BENCH_URL) -credential $(BENCH_KEY) \
		-scale $(BENCH_GS_SCALE)

## bench-gt-down: Stop the graph-traversal probe stack (platform, compose)
bench-gt-down:
	@if [ -f $(BENCH_PID) ]; then \
		kill $$(cat $(BENCH_PID)) 2>/dev/null || true; \
		rm -f $(BENCH_PID); \
	fi
	@$(MAKE) e2e-down

## bench-api-down: Stop the API study stack (platform, epmcp, fixture service, compose)
bench-api-down:
	@for pid in $(BENCH_PID) $(BENCH_EPMCP_PID) $(BENCH_APISVC_PID); do \
		if [ -f $$pid ]; then \
			kill $$(cat $$pid) 2>/dev/null || true; \
			rm -f $$pid; \
		fi; \
	done
	@$(MAKE) e2e-down

## bench-up: Start the compose stack, seed the bench warehouse, and run the platform (BENCH_ARM=a0|a1|a2|a3)
bench-up: e2e-up
	@echo "Seeding bench warehouse in Trino..."
	@$(BENCH_COMPOSE) cp bench/seed/trino/setup.sql trino:/tmp/bench-setup.sql
	@$(BENCH_COMPOSE) exec -T trino trino --file /tmp/bench-setup.sql
	@echo "Building release-style platform binary (no -race)..."
	@mkdir -p $(BUILD_DIR)
	$(GOBUILD) $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-bench $(CMD_DIR)
	@echo "Building benchrun..."
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/benchrun ./benchrun
	@if [ -f $(BENCH_PID) ]; then \
		echo "Stopping previous bench platform (pid $$(cat $(BENCH_PID)))..."; \
		kill $$(cat $(BENCH_PID)) 2>/dev/null || true; \
		while kill -0 $$(cat $(BENCH_PID)) 2>/dev/null; do sleep 1; done; \
		rm -f $(BENCH_PID); \
	fi
	@if curl -fsS $(BENCH_URL)/readyz >/dev/null 2>&1; then \
		echo "ERROR: something else is already serving $(BENCH_URL); run 'make bench-down' first"; exit 1; fi
	@echo "Starting platform ($(BENCH_CONFIG)) on $(BENCH_ADDR)..."
	@API_KEY_ADMIN=$(BENCH_KEY) LOG_LEVEL=info OTEL_METRICS_ADDR=$(BENCH_METRICS_ADDR) \
		$(BUILD_DIR)/$(BINARY_NAME)-bench --config $(BENCH_CONFIG) --transport http --address $(BENCH_ADDR) \
		> $(BENCH_LOG) 2>&1 & echo $$! > $(BENCH_PID)
	@echo "Waiting for readiness on $(BENCH_URL)/readyz ..."
	@for i in $$(seq 1 30); do \
		if curl -fsS $(BENCH_URL)/readyz >/dev/null 2>&1; then break; fi; \
		sleep 1; \
	done; \
	if ! curl -fsS $(BENCH_URL)/readyz >/dev/null 2>&1; then \
		echo "ERROR: platform did not become ready; see $(BENCH_LOG)"; tail -20 $(BENCH_LOG); exit 1; fi; \
	if ! kill -0 $$(cat $(BENCH_PID)) 2>/dev/null; then \
		echo "ERROR: bench platform exited after start (another server answered readiness?); see $(BENCH_LOG)"; \
		tail -20 $(BENCH_LOG); exit 1; fi
	@if [ "$(BENCH_SEED_PAGES)" = "0" ]; then \
		echo "Skipping knowledge-page seeding (BENCH_SEED_PAGES=0, cold-start empty baseline)."; \
		$(MAKE) --no-print-directory bench-seed-catalog-empty; \
	else \
		echo "Seeding knowledge pages (requires platform migrations, just applied on boot)..."; \
		$(BENCH_COMPOSE) exec -T postgres psql -q -U platform -d mcp_platform -v ON_ERROR_STOP=1 \
			< bench/seed/postgres/knowledge_pages.sql; \
		$(MAKE) --no-print-directory bench-seed-catalog; \
	fi
	@echo "Platform ready (pid $$(cat $(BENCH_PID)), arm $(BENCH_ARM))."

## bench-seed-catalog: Seed the platform catalog with the bench curation (descriptions, column units, tags, properties; needs a booted bench platform)
bench-seed-catalog:
	@echo "Seeding the platform catalog with the bench curation..."
	@$(BENCH_COMPOSE) exec -T postgres psql -q -U platform -d mcp_platform -v ON_ERROR_STOP=1 \
		< bench/seed/postgres/catalog.sql

## bench-seed-catalog-empty: Seed the cold-start empty baseline into the platform catalog (datasets present, undocumented; issue #963)
bench-seed-catalog-empty:
	@echo "Seeding the platform catalog with the undocumented bench datasets..."
	@$(BENCH_COMPOSE) exec -T postgres psql -q -U platform -d mcp_platform -v ON_ERROR_STOP=1 \
		< bench/seed/postgres/catalog_empty.sql

## bench-run: Run the benchmark (ARM must match bench-up; LLM=anthropic|scripted|claude-cli, SUITE=, K=, MODEL=)
bench-run:
	@mkdir -p build/bench-results
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/benchrun ./benchrun
	@echo "Resetting search-first gate state (discovery scopes persist in Postgres across runs)..."
	@$(BENCH_COMPOSE) exec -T postgres psql -q -U platform -d mcp_platform -v ON_ERROR_STOP=1 \
		-c "TRUNCATE search_gate_discovery"
	$(BUILD_DIR)/benchrun \
		-url $(BENCH_URL) \
		-credential $(BENCH_KEY) \
		-arm $(BENCH_ARM) \
		-tasks bench/tasks \
		-git-commit $$(git rev-parse HEAD) \
		-out build/bench-results/results-$(BENCH_ARM).json \
		$(if $(LLM),-llm $(LLM),) \
		$(if $(SCRIPT),-script $(SCRIPT),) \
		$(if $(SUITE),-suite $(SUITE),) \
		$(if $(K),-k $(K),) \
		$(if $(MODEL),-model $(MODEL),) \
		$(if $(BASELINE),-baseline $(BASELINE),)

## bench-smoke: Run the scripted (no-API-key) smoke against the running platform
bench-smoke:
	@$(MAKE) bench-run LLM=scripted SCRIPT=bench/tasks/scripted-smoke.json K=1

## bench-lifecycle: Run the S5 memory-insight-knowledge lifecycle protocols into a fresh per-run dir under build/bench-results/ (needs bench-up BENCH_ARM=a3; LLM=anthropic|scripted|claude-cli, K=, MODEL=, BASELINE=)
bench-lifecycle:
	@mkdir -p build/bench-results
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/benchrun ./benchrun
	@echo "Resetting search-first gate state (discovery scopes persist in Postgres across runs)..."
	@$(BENCH_COMPOSE) exec -T postgres psql -q -U platform -d mcp_platform -v ON_ERROR_STOP=1 \
		-c "TRUNCATE search_gate_discovery"
	@out_dir="build/bench-results/lifecycle-a3-$$(date +%Y%m%d-%H%M%S)-$$$$"; \
	mkdir "$$out_dir"; \
	echo "Lifecycle results dir: $$out_dir (each run gets its own dir; nothing is ever overwritten)"; \
	$(BUILD_DIR)/benchrun \
		-lifecycle \
		-arm a3 \
		-url $(BENCH_URL) \
		-credential $(BENCH_KEY) \
		-protocols bench/protocols \
		-git-commit $$(git rev-parse HEAD) \
		-out "$$out_dir/lifecycle-a3.json" \
		$(if $(LLM),-llm $(LLM),) \
		$(if $(SCRIPT),-script $(SCRIPT),) \
		$(if $(K),-k $(K),) \
		$(if $(MODEL),-model $(MODEL),) \
		$(if $(BASELINE),-baseline $(BASELINE),)

## bench-lifecycle-smoke: Run the scripted (no-API-key) lifecycle smoke against the running a3 platform
bench-lifecycle-smoke:
	@$(MAKE) bench-lifecycle LLM=scripted SCRIPT=bench/protocols/scripted-lifecycle-smoke.json K=1

## bench-lifecycle-report: Print the human summary of a lifecycle run (RESULTS=<run dir>/lifecycle-a3.json)
bench-lifecycle-report:
	@if [ -z "$(RESULTS)" ]; then \
		echo "ERROR: set RESULTS=<path to a lifecycle results JSON>. Available run dirs:"; \
		ls -d build/bench-results/lifecycle-a3-*/ 2>/dev/null || echo "  (none under build/bench-results/)"; \
		exit 1; fi
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/benchrun ./benchrun
	$(BUILD_DIR)/benchrun -lifecycle -summarize $(RESULTS)

## bench-supersede: Run the isolated supersede sub-benchmark into a fresh per-run dir under build/bench-results/ (issue #964; needs bench-up BENCH_ARM=a3; LLM=anthropic|scripted|claude-cli, K=, MODEL=, TEACH_BUDGET=)
bench-supersede:
	@mkdir -p build/bench-results
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/benchrun ./benchrun
	@echo "Resetting search-first gate state (discovery scopes persist in Postgres across runs)..."
	@$(BENCH_COMPOSE) exec -T postgres psql -q -U platform -d mcp_platform -v ON_ERROR_STOP=1 \
		-c "TRUNCATE search_gate_discovery"
	@out_dir="build/bench-results/supersede-a3-$$(date +%Y%m%d-%H%M%S)-$$$$"; \
	mkdir "$$out_dir"; \
	echo "Supersede results dir: $$out_dir (each run gets its own dir; nothing is ever overwritten)"; \
	$(BUILD_DIR)/benchrun \
		-supersede \
		-arm a3 \
		-url $(BENCH_URL) \
		-credential $(BENCH_KEY) \
		-protocols bench/protocols \
		-git-commit $$(git rev-parse HEAD) \
		-out "$$out_dir/supersede-a3.json" \
		$(if $(LLM),-llm $(LLM),) \
		$(if $(SCRIPT),-script $(SCRIPT),) \
		$(if $(K),-k $(K),) \
		$(if $(MODEL),-model $(MODEL),) \
		$(if $(TEACH_BUDGET),-teach-budget $(TEACH_BUDGET),)

## bench-supersede-smoke: Run the scripted (no-API-key) supersede sub-benchmark against the running a3 platform
bench-supersede-smoke:
	@$(MAKE) bench-supersede LLM=scripted SCRIPT=bench/protocols/scripted-lifecycle-smoke.json K=1

## bench-supersede-report: Print the human summary of a supersede run (RESULTS=<run dir>/supersede-a3.json)
bench-supersede-report:
	@if [ -z "$(RESULTS)" ]; then \
		echo "ERROR: set RESULTS=<path to a supersede results JSON>. Available run dirs:"; \
		ls -d build/bench-results/supersede-a3-*/ 2>/dev/null || echo "  (none under build/bench-results/)"; \
		exit 1; fi
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/benchrun ./benchrun
	$(BUILD_DIR)/benchrun -supersede -summarize $(RESULTS)

## bench-cold-start: Run the cold-start knowledge-growth curriculum into a fresh per-run dir under build/bench-results/ (issue #963; needs an empty-seeded a3: bench-up BENCH_ARM=a3 BENCH_SEED_PAGES=0; LLM=anthropic|scripted|claude-cli, K=, MODEL=, SETTLE=)
bench-cold-start:
	@mkdir -p build/bench-results
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/benchrun ./benchrun
	@echo "Resetting cold-start state so the baseline is truly empty (search gate, prior insights/changesets, promoted knowledge pages and catalog curation persist in Postgres across runs)..."
	@echo "  (CASCADE also clears portal_threads, which FK-references knowledge pages; the bench stack is disposable scratch state.)"
	@$(BENCH_COMPOSE) exec -T postgres psql -q -U platform -d mcp_platform -v ON_ERROR_STOP=1 \
		-c "TRUNCATE search_gate_discovery, memory_records, knowledge_changesets, portal_knowledge_pages, catalog_aspects, catalog_aspect_history CASCADE"
	@out_dir="build/bench-results/cold-start-a3-$$(date +%Y%m%d-%H%M%S)-$$$$"; \
	mkdir "$$out_dir"; \
	echo "Cold-start results dir: $$out_dir (each run gets its own dir; nothing is ever overwritten)"; \
	$(BUILD_DIR)/benchrun \
		-cold-start \
		-arm a3 \
		-url $(BENCH_URL) \
		-credential $(BENCH_KEY) \
		-curriculum bench/curriculum \
		-tasks bench/tasks \
		-git-commit $$(git rev-parse HEAD) \
		-out "$$out_dir/results.json" \
		$(if $(LLM),-llm $(LLM),) \
		$(if $(SCRIPT),-script $(SCRIPT),) \
		$(if $(K),-k $(K),) \
		$(if $(MODEL),-model $(MODEL),) \
		$(if $(SETTLE),-settle $(SETTLE),)

## bench-cold-start-smoke: Run the scripted (no-API-key) cold-start smoke against the running a3 platform (no cache-settle pause)
bench-cold-start-smoke:
	@$(MAKE) bench-cold-start LLM=scripted SCRIPT=bench/curriculum/scripted-cold-start-smoke.json K=1 SETTLE=0s

## bench-cold-start-report: Print the human summary (learning curve) of a cold-start run (RESULTS=<run dir>/results.json)
bench-cold-start-report:
	@if [ -z "$(RESULTS)" ]; then \
		echo "ERROR: set RESULTS=<path to a cold-start results.json>. Available run dirs:"; \
		ls -d build/bench-results/cold-start-a3-*/ 2>/dev/null || echo "  (none under build/bench-results/)"; \
		exit 1; fi
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/benchrun ./benchrun
	$(BUILD_DIR)/benchrun -cold-start -summarize $(RESULTS)

## bench-report: Print the human summary of the last run for BENCH_ARM
bench-report:
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/benchrun ./benchrun
	$(BUILD_DIR)/benchrun -summarize build/bench-results/results-$(BENCH_ARM).json

## bench-compare: Render the cross-arm comparison (arm-by-suite tables, bootstrap CIs) from all per-arm results
BENCH_COMPARE_OUT ?= build/bench-results/comparison.md
bench-compare:
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/benchrun ./benchrun
	@files=$$(ls build/bench-results/results-*.json 2>/dev/null | paste -sd, -); \
	if [ -z "$$files" ]; then echo "ERROR: no build/bench-results/results-*.json to compare"; exit 1; fi; \
	$(BUILD_DIR)/benchrun -compare "$$files" -compare-out $(BENCH_COMPARE_OUT)

## bench-report-knowledge-layer-pdf: Render the knowledge-layer benchmark report to PDF + HTML in build/report/ (needs pandoc + tectonic; not part of verify)
bench-report-knowledge-layer-pdf:
	@bash bench/reports/knowledge-layer/render-report.sh

## bench-report-knowledge-use-pdf: Render the knowledge-use benchmark report to PDF + HTML in build/report-knowledge-use/ (needs pandoc + tectonic; not part of verify)
bench-report-knowledge-use-pdf:
	@bash bench/reports/knowledge-use/render-report.sh

## bench-report-knowledge-pollution-pdf: Render the knowledge-pollution benchmark report to PDF + HTML in build/report-knowledge-pollution/ (needs pandoc + tectonic; not part of verify)
bench-report-knowledge-pollution-pdf:
	@bash bench/reports/knowledge-pollution/render-report.sh

## bench-report-graph-completion-pdf: Render the graph-completion benchmark report to PDF + HTML in build/report-graph-completion/ (needs pandoc + tectonic; not part of verify)
bench-report-graph-completion-pdf:
	@bash bench/reports/graph-completion/render-report.sh

## bench-report-check: Recompute the published benchmark reports from the committed archives and pin the headline numbers (stdlib python3, offline; part of verify)
bench-report-check:
	@echo "Recomputing the graph-completion report from bench/results/ (pins the published headline numbers, including the recorded instrument kill)..."
	@python3 bench/reports/graph-completion/graph_tables.py > /dev/null || \
		{ echo "FAIL: bench/reports/graph-completion/graph_tables.py — the archives no longer reproduce the published report."; \
		  python3 bench/reports/graph-completion/graph_tables.py | grep -A20 "T7"; exit 1; }
	@echo "Recomputing the knowledge-pollution report from bench/results/ (pins the published headline numbers)..."
	@python3 bench/reports/knowledge-pollution/pollution_tables.py > /dev/null || \
		{ echo "FAIL: bench/reports/knowledge-pollution/pollution_tables.py — the archives no longer reproduce the published report."; \
		  python3 bench/reports/knowledge-pollution/pollution_tables.py | grep -A15 "T13"; exit 1; }
	@echo "Recomputing the knowledge-use report tables (smoke: script must run clean)..."
	@python3 bench/reports/knowledge-use/pk_tables.py > /dev/null || \
		{ echo "FAIL: bench/reports/knowledge-use/pk_tables.py no longer runs against bench/results/knowledge-use/."; exit 1; }
	@echo "OK: report toolchains reproduce from the committed archives."

## bench-calibrate: Run the judge calibration and print its human-agreement rate (needs ANTHROPIC_API_KEY; uses the rubric's pinned model)
bench-calibrate:
	@cd bench && $(GO) build -o ../$(BUILD_DIR)/benchrun ./benchrun
	$(BUILD_DIR)/benchrun -calibrate -rubric bench/judge/rubric.yaml -calibration bench/judge/calibration.yaml

## bench-down: Stop the bench platform and the compose stack
bench-down:
	@if [ -f $(BENCH_PID) ]; then \
		echo "Stopping platform (pid $$(cat $(BENCH_PID)))..."; \
		kill $$(cat $(BENCH_PID)) 2>/dev/null || true; \
		rm -f $(BENCH_PID); \
	fi
	@$(MAKE) e2e-down

## bench-test: Build, vet, and unit-test the benchmark module itself
bench-test:
	@echo "Testing the benchmark module..."
	@cd bench && $(GO) build ./... && $(GO) vet ./... && $(GO) test ./...

## bench-lint: Full-module lint of the bench/ harness
##
## Mirrors CI's "Harness module checks" job, which runs golangci-lint over the
## whole bench module with NO only-new-issues scoping — unlike the main-module
## `lint` target, whose --new-from-patch scoping cannot see a finding that
## anchors on an unchanged line (e.g. a gocognit report on a func declaration
## whose body grew). bench/ is a separate Go module, so the root `lint` never
## reaches it at all; without this target a bench lint finding surfaces only
## in CI (PR #978's gocognit failure was exactly this gap).
bench-lint:
	@echo "Linting the benchmark module (full module, matching CI's harness job)..."
	@cd bench && $(GOLINT) run ./...