Feat/breaking change rework ranking

.github/workflows/ci.yml

@@ -133,7 +133,7 @@ jobs:
           make controller-gen
           make sync-crds
           kubectl apply -f config/crd/bases/
-      - name: Deploy E2E infrastructure (Prometheus + Registry)
+      - name: Deploy E2E infrastructure (Prometheus, Loki, Registry)
         run: make e2e-infra
       - name: Deploy operator
         run: |

.gitignore

@@ -43,3 +43,16 @@ docs/.hugo_build.lock
 # Generated CRD chart templates (produced by make sync-crds in CI)
 charts/drop-crds/templates/drop.corewire.io_*.yaml
 charts/drop/templates/crds-drop.corewire.io_*.yaml
+
+# Imported research archives (always unpack; never commit zip bundles)
+research/**/*.zip
+
+# Python cache artifacts
+__pycache__/
+*.pyc
+
+# Local Python virtual environments
+.venv/
+
+# Local docs image generation workspace artifacts
+docs/static/images/src/usr/

Makefile

@@ -103,7 +103,7 @@ uninstall: manifests kustomize ## Uninstall CRDs from cluster.
 	$(KUSTOMIZE) build config/crd | $(KUBECTL) delete --ignore-not-found -f -
 
 .PHONY: e2e-infra
-e2e-infra: ## Deploy Prometheus + Registry for E2E/dev.
+e2e-infra: ## Deploy Prometheus, Loki, and Registry for E2E/dev.
 	@chmod +x hack/e2e-infra/setup.sh && hack/e2e-infra/setup.sh
 
 ##@ Docker
@@ -122,6 +122,9 @@ kind-load: docker-build ## Build and load image into kind.
 
 ##@ Helm & Docs
 
+DOCS_IMG_SRC_DIR ?= docs/static/images/src
+DOCS_IMG_VENV ?= $(DOCS_IMG_SRC_DIR)/.venv
+
 .PHONY: helm-lint
 helm-lint: ## Lint the Helm chart.
 	helm lint charts/drop
@@ -143,6 +146,88 @@ docs-gen-check: docs-gen ## Verify generated AI docs are up to date.
 	@git diff --exit-code knowledge.yaml llms.txt llms-full.txt docs/static/llms-full.txt .github/copilot-instructions.md .cursorrules AGENTS.md docs/content/docs/reference/_generated_*.md || \
 		(echo "ERROR: generated docs are out of date — run 'make docs-gen'" && exit 1)
 
+.PHONY: docs-images-setup
+docs-images-setup: ## Create docs image venv and install chart dependencies.
+	@cd $(DOCS_IMG_SRC_DIR) && \
+	python3 -m venv .venv && \
+	. .venv/bin/activate && \
+	pip install -r requirements.txt
+
+.PHONY: docs-images-gen
+docs-images-gen: docs-images-setup ## Generate docs SVG charts from sample data.
+	@cd $(DOCS_IMG_SRC_DIR) && \
+	. .venv/bin/activate && \
+	python signal-eventpulltime.py && \
+	python discovery-charts.py && \
+	python research-doc-assets.py && \
+	python research-tikz-assets.py
+
+.PHONY: static
+static: docs-images-gen ## Generate all maintained static docs graphics.
+
+##@ Research
+
+RESEARCH_TEX_DIR ?= research/tex
+RESEARCH_TEX_FILE ?= paper.tex
+RESEARCH_BENCH_DIR ?= research/benchmark/evaluator
+RESEARCH_BENCH_VENV ?= $(RESEARCH_BENCH_DIR)/.venv
+RESEARCH_BENCH_RESULTS_DIR ?= research/benchmark/results
+RESEARCH_BENCH_RESULTS_DISCOVERY_20RUNS ?= $(RESEARCH_BENCH_RESULTS_DIR)/discovery-strategy-20runs
+RESEARCH_BENCH_RESULTS_ORACLE_20RUNS ?= $(RESEARCH_BENCH_RESULTS_DIR)/oracle-gap-strategy-20runs
+RESEARCH_BENCH_RESULTS_CACHE_20RUNS ?= $(RESEARCH_BENCH_RESULTS_DIR)/ci-image-cache-20runs
+
+.PHONY: research-tex-build
+research-tex-build: ## Build research PDF from TeX source (override RESEARCH_TEX_FILE=<file.tex>).
+	@cd $(RESEARCH_TEX_DIR) && \
+	if command -v latexmk >/dev/null 2>&1; then \
+		latexmk -pdf -interaction=nonstopmode -halt-on-error $(RESEARCH_TEX_FILE); \
+	elif command -v pdflatex >/dev/null 2>&1; then \
+		pdflatex -interaction=nonstopmode -halt-on-error $(RESEARCH_TEX_FILE) && \
+		pdflatex -interaction=nonstopmode -halt-on-error $(RESEARCH_TEX_FILE); \
+	else \
+		echo "ERROR: latexmk/pdflatex not found"; exit 1; \
+	fi
+
+.PHONY: research-bench-setup
+research-bench-setup: ## Create benchmark venv and install Python dependencies.
+	@cd $(RESEARCH_BENCH_DIR) && \
+	python3 -m venv .venv && \
+	. .venv/bin/activate && \
+	pip install -r requirements.txt
+
+.PHONY: research-bench-generate
+research-bench-generate: ## Generate synthetic benchmark dataset.
+	@cd $(RESEARCH_BENCH_DIR) && \
+	. .venv/bin/activate && \
+	python generate_synthetic_day.py --out data --jobs 25000 --nodes 100 --images 30 --seed 20260621
+
+.PHONY: research-bench-replay
+research-bench-replay: ## Run replay policy evaluation from benchmark data.
+	@cd $(RESEARCH_BENCH_DIR) && \
+	. .venv/bin/activate && \
+	python evaluate_replay.py --data data --out outputs
+
+.PHONY: research-bench-discovery
+research-bench-discovery: ## Evaluate discovery strategies from benchmark data.
+	@cd $(RESEARCH_BENCH_DIR) && \
+	. .venv/bin/activate && \
+	python evaluate_discovery_strategies.py --data data --out outputs/strategy_eval
+
+.PHONY: research-bench-plot
+research-bench-plot: ## Render example pipeline Gantt figure.
+	@cd $(RESEARCH_BENCH_DIR) && \
+	. .venv/bin/activate && \
+	python plot_pipeline_gantt.py --modeled-jobs outputs/modeled_jobs_no_prewarming.csv --out figures/example_gantt.png
+
+.PHONY: research-bench-20runs
+research-bench-20runs: ## Run 20-run discovery strategy benchmark batch.
+	@cd $(RESEARCH_BENCH_DIR) && \
+	. .venv/bin/activate && \
+	python run_discovery_strategy_20runs.py
+
+.PHONY: research-bench-all
+research-bench-all: research-bench-generate research-bench-replay research-bench-discovery research-bench-plot ## Run full synthetic benchmark workflow.
+
 .PHONY: tools
 tools: ## Install local tooling and check optional docs/chart binaries.
 	@$(MAKE) kustomize controller-gen setup-envtest golangci-lint chainsaw

README.md

@@ -9,7 +9,7 @@
 </p>
 
 
-A Kubernetes operator that pre-pulls container images onto nodes — safely, with pacing, and with automatic discovery. 
+A Kubernetes operator that pre-pulls container images onto nodes — safely, with pacing, and with automatic discovery.
 
 ## Why
 
@@ -45,6 +45,8 @@ VERSION="$(curl -fsSL https://api.github.com/repos/corewire/drop/releases/latest
 
 # Install CRDs first so upgrades stay predictable
 helm install drop-crds oci://ghcr.io/corewire/charts/drop-crds \
+  --namespace drop-system \
+  --create-namespace \
   --version "$VERSION"
 
 # Install the operator
@@ -115,18 +117,19 @@ spec:
   maxImages: 20
   # Only keep images from your internal registry (regex filter, optional)
   imageFilter: "registry.example.com/.*"
-  sources:
-    - type: prometheus
+  queries:
+    - name: runner-image-usage
+      type: prometheus
       prometheus:
         # Any Prometheus-compatible API (Prometheus, Thanos, Mimir, VictoriaMetrics)
         endpoint: https://mimir.example.com
         # Aggregate over the last 7 days using query_range; counts container
         # instances per image across the window to produce a usage score
+        queryType: range
         lookback: 168h
         # Resolution step for range queries (default: 5m)
         step: 5m
         # PromQL query — MUST return results with an "image" label.
-        # The result value becomes the ranking score (higher = cached first).
         query: |
           count(
             container_memory_working_set_bytes{
@@ -135,9 +138,18 @@ spec:
             }
           ) by (image)
       # Optional: Secret in the Drop pod namespace (default: drop-system)
-      # Supported keys: token, username, password, ca.crt, tls.crt, tls.key
+      # Supported keys: token, username, password, ca.crt, tls.crt, tls.key, headers.<name>
       secretRef:
         name: prometheus-creds
+  signals:
+    - name: total-usage
+      query: runner-image-usage
+      type: aggregate
+      aggregate:
+        method: sum
+  ranking:
+    strategy: signal
+    signal: total-usage
 ---
 # --- 3. CachedImageSet: ties discovery + policy together, targets nodes ---
 apiVersion: drop.corewire.io/v1alpha1
@@ -304,18 +316,19 @@ spec:
   maxImages: 30
   # Only keep images matching this regex (optional)
   imageFilter: "registry.example.com/.*"
-  sources:
-    - type: prometheus
+  queries:
+    - name: runner-image-usage
+      type: prometheus
       prometheus:
         # Any Prometheus-compatible API (Prometheus, Thanos, Mimir, VictoriaMetrics)
         endpoint: https://mimir.example.com
         # Aggregate over the last 7 days (uses query_range, sums values per image)
         # Omit for a point-in-time instant query instead
+        queryType: range
         lookback: 168h
         # Resolution step for range queries (default: 5m)
         step: 5m
         # PromQL query — MUST return results with an "image" label.
-        # The result value becomes the ranking score (higher = cached first).
         query: |
           count(
             container_memory_working_set_bytes{
@@ -327,6 +340,15 @@ spec:
       # Supported keys: token, username, password, ca.crt, tls.crt, tls.key, headers.<name>
       secretRef:
         name: prometheus-creds
+  signals:
+    - name: total-usage
+      query: runner-image-usage
+      type: aggregate
+      aggregate:
+        method: sum
+  ranking:
+    strategy: signal
+    signal: total-usage
 ---
 apiVersion: drop.corewire.io/v1alpha1
 kind: CachedImageSet
@@ -342,7 +364,11 @@ spec:
       tag: "3.19"
 ```
 
-### Use case: discover and cache application tags from a registry
+### Use case: discover and cache GitLab runner helper images from a registry
+
+GitLab runner helper tags carry an arch/flavor prefix (e.g. `x86_64-v17.5.0`).
+Drop extracts the embedded version automatically; `versionPattern` is shown for
+clarity but is optional here.
 
 ```yaml
 apiVersion: v1
@@ -362,24 +388,30 @@ metadata:
 spec:
   syncInterval: 15m
   maxImages: 10
-  sources:
-    - type: registry
+  queries:
+    - name: registry-tags
+      type: registry
       registry:
         # Registry base URL
-        url: https://registry.example.com
+        url: https://registry.gitlab.com
         # Repositories to list tags from
         repositories:
-          - team/frontend
-          - team/backend
-          - team/worker
-        # Only discover semver tags (regex on tag name)
-        tagFilter: "^v[0-9]+\\."
-        # Keep only the last 3 matching tags returned by the registry
+          - gitlab-org/gitlab-runner/gitlab-runner-helper
+        # Only discover x86_64 semver tags (regex on tag name)
+        tagFilter: "^x86_64-v[0-9]+\\."
+        # Optional: pin where the version lives in the tag (capture group 1)
+        versionPattern: "x86_64-v(.+)"
+        # Optional: skip straight to the x86_64-v* tags (registry `last` cursor)
+        tagSeek: "x86_64-u~"
+        # Optional: cap tags fetched per repo before filtering (default 1000)
+        maxScan: 2000
+        # Keep only the 3 newest matching tags (newest first)
         topX: 3
       # Optional: Secret in the Drop pod namespace (default: drop-system)
       # Supported keys: token, username, password, ca.crt, tls.crt, tls.key, headers.<name>
       secretRef:
         name: registry-api-creds
+  # No signals/ranking needed: registry tags are returned newest-first.
 ---
 apiVersion: drop.corewire.io/v1alpha1
 kind: CachedImageSet
@@ -390,27 +422,6 @@ spec:
     name: latest-app-tags
 ```
 
-## Quick Start
-
-```bash
-# Install CRDs and operator via Helm
-helm install drop charts/drop -n drop-system --create-namespace
-
-# Cache a single image
-kubectl apply -f - <<YAML
-apiVersion: drop.corewire.io/v1alpha1
-kind: CachedImage
-metadata:
-  name: nginx
-spec:
-  image: docker.io/library/nginx
-  tag: 1.25-alpine
-YAML
-
-# Check status
-kubectl get cachedimage nginx -o wide
-```
-
 ## CRDs
 
 All resources are **cluster-scoped** under `drop.corewire.io/v1alpha1`.
@@ -442,24 +453,53 @@ dev-set    AllReady    3/3     3         dev-registry   1h
 web-apps   Degraded    1/3     3                        10m
 
 $ kubectl get discoverypolicies
-NAME             STATUS              SOURCES   IMAGES   LASTSYNC   AGE
-dev-registry     Synced              1         3        30s        1h
-broken-prom      ConnectionRefused   1         0                   5m
-bad-auth         Unauthorized        1         0                   2m
+NAME             STATUS              IMAGES   LASTSYNC   AGE
+dev-registry     Synced              3        30s        1h
+broken-prom      ConnectionRefused   0                   5m
+bad-auth         Unauthorized        0                   2m
 ```
 
+## Research And Benchmark
+
+The repo includes the replay benchmark used in the research docs and paper.
+
+```bash
+# Synthetic benchmark day + replay
+make research-bench-setup
+make research-bench-generate
+make research-bench-replay
+make research-bench-discovery
+
+# Or fetch real-cluster inputs from Prometheus + Loki
+cd research/benchmark/evaluator
+. .venv/bin/activate
+python fetch_cluster_data.py \
+  --prometheus-url http://localhost:9090 \
+  --loki-url http://localhost:3100 \
+  --out data
+```
+
+See `research/benchmark/evaluator/README.md` for the full input schema and live-cluster workflow.
+
 ## Development
 
 ```bash
-# Prerequisites: Go 1.23+, Kind, Tilt, Helm
-make generate      # deepcopy
-make manifests     # CRDs + RBAC
+# Prerequisites: Go 1.26+, Kind, Tilt, Helm
+make codegen       # deepcopy + CRDs + generated docs
 go build ./...     # compile
+make test          # unit tests
+make lint          # golangci-lint
 
-# Local dev loop (Kind + Tilt)
+# Local dev loop: creates kind, deploys Drop, Prometheus, Loki, Grafana, docs
 tilt up
 ```
 
 ## Docs
 
 Full documentation at **[corewire.github.io/drop/](https://corewire.github.io/drop/)** (GitHub Pages).
+
+```bash
+make static        # regenerate maintained docs graphics
+make docs-gen      # regenerate AI-facing docs
+cd docs && hugo server --buildDrafts --port 1313
+```