B-Sides app code (indexes load from dataset repos at boot)

.pytest_cache/.gitignore

@@ -0,0 +1,2 @@
+# Created by pytest automatically.
+*

.pytest_cache/CACHEDIR.TAG

@@ -0,0 +1,4 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by pytest.
+# For information about cache directory tags, see:
+#	https://bford.info/cachedir/spec.html

.pytest_cache/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.

.pytest_cache/v/cache/nodeids

@@ -0,0 +1,117 @@
+[
+  "tests/test_config.py::test_collection_validation_names_missing_credential[env0-HF_TOKEN]",
+  "tests/test_config.py::test_collection_validation_names_missing_credential[env1-OPENAI_API_KEY]",
+  "tests/test_config.py::test_crawl_end_is_an_explicit_inclusive_upper_boundary",
+  "tests/test_config.py::test_defaults_match_the_production_crawl_contract",
+  "tests/test_config.py::test_environment_overrides_are_parsed_without_storing_secret_values",
+  "tests/test_config.py::test_invalid_settings_are_rejected[env0-BSIDES_MODE]",
+  "tests/test_config.py::test_invalid_settings_are_rejected[env1-Hub request budget]",
+  "tests/test_config.py::test_invalid_settings_are_rejected[env2-Hub request budget]",
+  "tests/test_config.py::test_invalid_settings_are_rejected[env3-embedding dimensions]",
+  "tests/test_config.py::test_invalid_settings_are_rejected[env4-overlap]",
+  "tests/test_config.py::test_invalid_settings_are_rejected[env5-queue multiplier]",
+  "tests/test_config.py::test_invalid_settings_are_rejected[env6-embedding workers]",
+  "tests/test_config.py::test_invalid_settings_are_rejected[env7-embedding token rate]",
+  "tests/test_config.py::test_invalid_settings_are_rejected[env8-checkpoint interval]",
+  "tests/test_config.py::test_invalid_settings_are_rejected[env9-progress interval]",
+  "tests/test_config.py::test_search_mode_does_not_require_collection_credentials",
+  "tests/test_runtime.py::test_app_registers_docker_corpus_configuration",
+  "tests/test_runtime.py::test_app_registers_kernel_corpus_configuration",
+  "tests/test_runtime.py::test_docker_facets_and_search_use_container_response_shape",
+  "tests/test_runtime.py::test_docker_index_download_allows_only_published_search_files",
+  "tests/test_runtime.py::test_docker_semantic_search_without_a_key_is_unavailable_not_a_crash",
+  "tests/test_runtime.py::test_endpoints_503_until_the_index_is_ready",
+  "tests/test_runtime.py::test_facets_and_picks_still_answer",
+  "tests/test_runtime.py::test_failed_docker_load_does_not_affect_model_search",
+  "tests/test_runtime.py::test_failed_kernel_load_does_not_affect_model_search",
+  "tests/test_runtime.py::test_frontend_checks_model_exclusions_by_default",
+  "tests/test_runtime.py::test_frontend_defaults_docker_to_recipes_with_an_archive_toggle",
+  "tests/test_runtime.py::test_frontend_escapes_every_docker_card_value",
+  "tests/test_runtime.py::test_frontend_keeps_model_size_as_precise_billion_boxes",
+  "tests/test_runtime.py::test_frontend_links_docker_artifacts_to_valid_hugging_face_targets",
+  "tests/test_runtime.py::test_frontend_offers_all_three_corpora",
+  "tests/test_runtime.py::test_frontend_restores_default_exclusions_when_clearing_the_deck",
+  "tests/test_runtime.py::test_frontend_routes_every_corpus_through_one_url_builder",
+  "tests/test_runtime.py::test_frontend_tracks_docker_in_every_corpus_state_map",
+  "tests/test_runtime.py::test_kernel_facets_and_search_use_kernel_response_shape",
+  "tests/test_runtime.py::test_model_search_exclusions_are_explicit_and_api_compatible",
+  "tests/test_runtime.py::test_models_client_remains_the_oai_compatibility_shim",
+  "tests/test_runtime.py::test_reload_endpoint_hot_swaps_only_the_docker_corpus",
+  "tests/test_runtime.py::test_reload_endpoint_hot_swaps_only_the_kernel_corpus",
+  "tests/test_runtime.py::test_reload_of_an_unknown_corpus_is_a_404",
+  "tests/test_runtime.py::test_reload_with_a_wrong_token_is_403",
+  "tests/test_runtime.py::test_reload_with_an_empty_body_is_rejected",
+  "tests/test_runtime.py::test_reload_with_the_right_token_swaps_the_index",
+  "tests/test_runtime.py::test_reload_without_a_configured_token_is_503",
+  "tests/test_runtime.py::test_search_defaults_to_the_models_corpus",
+  "tests/test_runtime.py::test_search_index_download_excludes_crawler_staging",
+  "tests/test_runtime.py::test_search_query_uses_the_loaded_index_dimensions",
+  "tests/test_runtime.py::test_search_response_keeps_the_total_models_envelope",
+  "tests/test_runtime.py::test_semantic_search_without_a_key_is_unavailable_not_a_crash",
+  "tests/test_runtime.py::test_semantic_searches_use_their_assigned_corpus_clients",
+  "tests/test_runtime.py::test_unknown_corpus_is_a_404",
+  "tests/test_search_indexes.py::test_build_where_covers_every_model_filter",
+  "tests/test_search_indexes.py::test_build_where_empty_request_is_neutral",
+  "tests/test_search_indexes.py::test_build_where_executes_against_real_sqlite",
+  "tests/test_search_indexes.py::test_card_decodes_json_columns_and_rounds_score",
+  "tests/test_search_indexes.py::test_card_without_score_omits_it",
+  "tests/test_search_indexes.py::test_compute_facets_shape_matches_the_legacy_payload",
+  "tests/test_search_indexes.py::test_container_archive_rows_appear_when_artifact_kind_filter_is_absent",
+  "tests/test_search_indexes.py::test_container_card_decodes_json_arrays_and_preserves_empty_arrays",
+  "tests/test_search_indexes.py::test_container_defaults_to_requested_recipe_filter",
+  "tests/test_search_indexes.py::test_container_facets_count_scalars_arrays_and_booleans",
+  "tests/test_search_indexes.py::test_container_filters_are_anded_across_groups_and_ored_within_group",
+  "tests/test_search_indexes.py::test_container_query_text_is_preserved_for_semantic_search",
+  "tests/test_search_indexes.py::test_container_scalar_boolean_and_json_filters_execute_against_sqlite",
+  "tests/test_search_indexes.py::test_db_is_thread_local_readonly_and_generation_scoped",
+  "tests/test_search_indexes.py::test_download_index_requests_dataset_files_into_spec_dir",
+  "tests/test_search_indexes.py::test_embed_query_caps_input_at_max_chars",
+  "tests/test_search_indexes.py::test_embed_query_uses_spec_model_and_selected_matrix_dimensions",
+  "tests/test_search_indexes.py::test_embed_query_without_client_names_the_selected_credential",
+  "tests/test_search_indexes.py::test_embed_query_without_matrix_is_unavailable",
+  "tests/test_search_indexes.py::test_extract_constraints_empty_remainder_skips_embedding",
+  "tests/test_search_indexes.py::test_extract_constraints_never_loosens_explicit_filters",
+  "tests/test_search_indexes.py::test_extract_constraints_pulls_dates_params_downloads_and_flags",
+  "tests/test_search_indexes.py::test_failed_download_keeps_serving_the_previous_index",
+  "tests/test_search_indexes.py::test_kernel_adapter_ignores_legacy_model_and_unknown_filters",
+  "tests/test_search_indexes.py::test_kernel_array_filter_values_are_or_within_one_category",
+  "tests/test_search_indexes.py::test_kernel_card_decodes_arrays_and_returns_facts",
+  "tests/test_search_indexes.py::test_kernel_facets_count_members_of_json_arrays",
+  "tests/test_search_indexes.py::test_kernel_filters_execute_against_real_sqlite",
+  "tests/test_search_indexes.py::test_kernel_query_text_is_preserved_for_semantic_search",
+  "tests/test_search_indexes.py::test_kernel_structured_page_uses_kernel_envelope_contract",
+  "tests/test_search_indexes.py::test_load_accepts_empty_index",
+  "tests/test_search_indexes.py::test_load_isolates_downloader_failure",
+  "tests/test_search_indexes.py::test_load_pulls_dataset_when_files_are_missing",
+  "tests/test_search_indexes.py::test_load_rejects_dimension_mismatch",
+  "tests/test_search_indexes.py::test_load_rejects_matrix_rank_not_two",
+  "tests/test_search_indexes.py::test_load_rejects_non_finite_values",
+  "tests/test_search_indexes.py::test_load_rejects_row_count_mismatch",
+  "tests/test_search_indexes.py::test_load_rejects_rows_outside_matrix_bounds",
+  "tests/test_search_indexes.py::test_load_rejects_sqlite_that_fails_quick_check",
+  "tests/test_search_indexes.py::test_load_validates_marks_ready_and_computes_facets",
+  "tests/test_search_indexes.py::test_load_without_downloader_never_imports_hub_when_files_exist",
+  "tests/test_search_indexes.py::test_malformed_config_remains_searchable_during_quantization_exclusion",
+  "tests/test_search_indexes.py::test_model_adapter_exposes_spec_result_key_and_card_columns",
+  "tests/test_search_indexes.py::test_model_adapter_ignores_adapter_filters",
+  "tests/test_search_indexes.py::test_model_exclusions_are_neutral_by_default",
+  "tests/test_search_indexes.py::test_model_exclusions_match_family_evidence",
+  "tests/test_search_indexes.py::test_model_family_exclusion_matches_expanded_mistral_terms",
+  "tests/test_search_indexes.py::test_quantization_exclusion_requires_strong_evidence",
+  "tests/test_search_indexes.py::test_registry_isolates_a_broken_corpus_from_a_healthy_one",
+  "tests/test_search_indexes.py::test_registry_start_loading_runs_isolated_threads",
+  "tests/test_search_indexes.py::test_registry_unknown_key_raises_keyerror",
+  "tests/test_search_indexes.py::test_reload_does_not_skip_the_download_step",
+  "tests/test_search_indexes.py::test_reload_invalidates_connections_to_the_replaced_file",
+  "tests/test_search_indexes.py::test_reload_rejecting_a_bad_publish_keeps_serving_the_old_index",
+  "tests/test_search_indexes.py::test_reload_rejects_a_publish_whose_rows_do_not_match_the_matrix",
+  "tests/test_search_indexes.py::test_reload_swaps_in_the_freshly_published_index",
+  "tests/test_search_indexes.py::test_search_request_keeps_optional_adapter_filters",
+  "tests/test_search_indexes.py::test_semantic_rank_empty_candidates_skip_embedding",
+  "tests/test_search_indexes.py::test_semantic_rank_page_beyond_window_returns_total_but_no_cards",
+  "tests/test_search_indexes.py::test_semantic_rank_propagates_unavailable_embedding",
+  "tests/test_search_indexes.py::test_semantic_rank_scores_orders_and_paginates",
+  "tests/test_search_indexes.py::test_semantic_rank_uses_candidate_scoring_for_small_filtered_sets",
+  "tests/test_search_indexes.py::test_structured_page_orders_counts_and_paginates",
+  "tests/test_search_indexes.py::test_structured_page_unknown_sort_falls_back_to_newest"
+]

Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+ENV BSIDES_MODE=search
+# git isn't in the slim base, but HF's Space builder injects a
+# `git config --global user.email ...` step after our layers — it 127s without git.
+RUN apt-get update && apt-get install -y --no-install-recommends git \
+    && rm -rf /var/lib/apt/lists/*
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Retrieval only: the collector and its job scripts are not part of this image.
+COPY app.py staff_picks.json ./
+COPY bsides/__init__.py bsides/config.py bsides/search_indexes.py bsides/
+COPY static static
+
+# index is pulled from the b-sides-index dataset at boot (see app.py)
+RUN mkdir -p /app/index && chmod 777 /app/index
+RUN mkdir -p /tmp/bsides && chmod 777 /tmp/bsides
+
+EXPOSE 7860
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,11 +1,62 @@
 ---
-title: B Sides V2
-emoji: 👁
-colorFrom: pink
-colorTo: gray
+title: B-Sides V2
+emoji: 🔎
+colorFrom: red
+colorTo: yellow
 sdk: docker
+app_port: 7860
 pinned: false
-license: mit
+short_description: Building live to let the obscure breathe new life
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🔎 B-Sides V2 — the full text-model record
+
+B-Sides V2 is a fresh, searchable full-history pressing of Hugging Face text
+models.
+
+B-Sides index is more interesting than "models nobody uses." It maps the shadow
+infrastructure of open ML: abandoned experiments, regional language work,
+architecture probes, creative utilities, and research releases that conventional
+popularity rankings erase.
+
+The production collector walks both official Hub pipeline streams from newest
+to oldest until they are exhausted:
+
+- `text-generation`
+- `text2text-generation`
+
+It deduplicates full repository IDs. There are no family, popularity, download,
+parameter, likes, license, gating, private-visibility, or source-content
+exclusions: every discovered model receives a metadata embedding, and available
+cards/configuration/source are added to it.
+
+For every survivor, B-Sides fetches the root model card plus every Python file at
+the discovered commit SHA, chunks them by source lines, and sends deterministic
+requests to `text-embedding-3-small` through the OpenAI Batch API. The collector
+checkpoints its SQLite state to
+[`juiceb0xc0de/b-sides-v2-index`](https://huggingface.co/datasets/juiceb0xc0de/b-sides-v2-index),
+resumes after restarts, and moves into overlapping tail scans after the initial
+backfill.
+
+All Hub traffic shares a conservative governor: at most 2,400 counted or
+reserved requests per 300 seconds against the confirmed 3,000-request hard cap.
+
+The existing search index remains online while this full-history pressing is
+built. New search activation stays gated until coverage, chunk/vector alignment,
+dimensions, finite values, and checksums validate.
+
+Collector progress is available at `/api/crawl-status`.
+
+## Runtime configuration
+
+- `BSIDES_MODE=search|collect|both` (default: `both`)
+- `BSIDES_DATASET` (default: `juiceb0xc0de/b-sides-v2-index`)
+- `BSIDES_RUN_ID` (default: `v2`)
+- `BSIDES_CRAWL_END` (optional ISO-8601 exclusive upper boundary)
+- `BSIDES_HUB_REQUESTS_PER_5M` (default: `2400`, must stay below `3000`)
+- `BSIDES_CHECKPOINT_EVERY_REPOS` (default: `2500`)
+- `BSIDES_TAIL_INTERVAL_SECONDS` (default: `900`)
+- `BSIDES_TAIL_OVERLAP_IDS` (default: `100`)
+- Space secrets: `HF_TOKEN` and `OPENAI_API_KEY`
+
+Pressed by [juiceb0xc0de](https://huggingface.co/juiceb0xc0de).

app.py

@@ -0,0 +1,265 @@
+"""
+B-Sides — deep search for indie & vintage text-generation LLMs.
+
+FastAPI backend. A thin HTTP layer over `bsides.search_indexes`: the registry
+owns downloading, loading, validation, facets and ranking for every corpus
+(models, kernels and Docker images). This module owns the wire shape and
+nothing else.
+
+Retrieval only. Collection lives in its own job repos: this Space reads the
+published indexes and never crawls, so nothing here imports the collector.
+
+Endpoints:
+    GET  /                  static frontend
+    GET  /api/facets        filter options + counts for one corpus
+    POST /api/search        semantic + structured search over one corpus
+    POST /api/reload        token-gated hot-swap of a freshly published index
+    GET  /api/picks         the daily staff-pick spread (models corpus)
+"""
+
+import hmac
+import os
+import threading
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+import orjson
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import FileResponse, Response
+from openai import OpenAI
+from pydantic import BaseModel
+
+from bsides.config import Settings
+from bsides.search_indexes import (
+    PAGE_SIZE,
+    ContainerAdapter,
+    IndexRegistry,
+    IndexSpec,
+    KernelAdapter,
+    ModelAdapter,
+    SearchReq,
+    UnavailableError,
+    semantic_rank,
+    structured_page,
+)
+
+BASE = Path(__file__).parent
+INDEX_DIR = Path(os.environ.get('BSIDES_INDEX', BASE / 'index'))
+INDEX_DATASET = os.environ.get('BSIDES_DATASET', 'juiceb0xc0de/b-sides-v2-index')
+KERNEL_DATASET = os.environ.get(
+    'BSIDES_KERNEL_DATASET', 'juiceb0xc0de/b-sides-v2-kernels')
+CONTAINER_DATASET = os.environ.get(
+    'BSIDES_CONTAINER_DATASET', 'juiceb0xc0de/b-sides-v2-containers')
+
+EMBED_MODEL = 'text-embedding-3-small'   # must match the corpus embedding model
+MODELS = 'models'                        # default corpus for every endpoint
+KERNELS = 'kernels'
+DOCKER = 'docker'
+QUERY_CREDENTIALS = {
+    MODELS: 'OPENAI_API_KEY',
+    KERNELS: 'OPENAI_KERNEL_API_KEY',
+    DOCKER: 'OPENAI_DOCKER_API_KEY',
+}
+
+# The published matrix width is a property of the crawl that produced it, so the
+# spec's expected width comes from the same Settings the collector embeds with.
+# It is a validation expectation only — the width actually sent to the embedding
+# API is read off the loaded matrix (see search_indexes.embed_query).
+EMBED_DIMENSIONS = Settings.from_env(os.environ).embedding_dimensions
+
+
+@asynccontextmanager
+async def _lifespan(_application: FastAPI):
+    _startup()
+    yield
+
+
+app = FastAPI(title='B-Sides', lifespan=_lifespan)
+
+
+def _openai_client(env_name: str):
+    key = os.environ.get(env_name)
+    return OpenAI(api_key=key) if key else None
+
+
+query_clients = {
+    corpus: _openai_client(credential)
+    for corpus, credential in QUERY_CREDENTIALS.items()
+}
+oai = query_clients[MODELS]
+
+# ── corpora ───────────────────────────────────────────────────────────────────
+# Registration is import-time and cheap; the 1.4 GB matrix — and on a cold boot
+# the ~800 MB index download — load in background threads kicked off by the
+# lifespan startup. That is the whole point: uvicorn binds :7860 immediately, so
+# HF's Space watchdog stops re-spawning duplicate workers while the matrix is
+# still streaming off disk. Until an index is ready its endpoints 503.
+MODEL_SPEC = IndexSpec(
+    key=MODELS,
+    dataset_id=INDEX_DATASET,
+    local_dir=INDEX_DIR,
+    table='models',
+    id_column='model_id',
+    embed_model=EMBED_MODEL,
+    dimensions=EMBED_DIMENSIONS,
+)
+KERNEL_SPEC = IndexSpec(
+    key=KERNELS,
+    dataset_id=KERNEL_DATASET,
+    local_dir=INDEX_DIR / KERNELS,
+    table='kernels',
+    id_column='repo_id',
+    embed_model=EMBED_MODEL,
+    dimensions=256,
+)
+DOCKER_SPEC = IndexSpec(
+    key=DOCKER,
+    dataset_id=CONTAINER_DATASET,
+    local_dir=INDEX_DIR / DOCKER,
+    table='containers',
+    id_column='repo_id',
+    embed_model=EMBED_MODEL,
+    dimensions=256,
+)
+
+registry = IndexRegistry()
+registry.register(ModelAdapter(MODEL_SPEC))
+registry.register(KernelAdapter(KERNEL_SPEC))
+registry.register(ContainerAdapter(DOCKER_SPEC))
+
+
+def _ready_index(corpus: str):
+    """Resolve a corpus key to a loaded index, or fail the way HTTP expects."""
+    try:
+        index = registry.index(corpus)
+    except KeyError:
+        raise HTTPException(404, f'unknown corpus: {corpus}') from None
+    if not index.ready.is_set():
+        # `error` set means load() failed and recorded why — that state is
+        # permanent until the artifact is fixed, so "retry in a moment" would
+        # be a lie. (Reload failures keep ready set and never land here.)
+        if index.error is not None:
+            raise HTTPException(
+                503, f'index failed to load: {index.error}')
+        raise HTTPException(503, 'index still loading — retry in a moment')
+    return index
+
+
+def _startup():
+    # bind first, load in the background — see the note above MODEL_SPEC.
+    registry.start_loading()
+    print('startup: :7860 binding while the index loads in the background',
+          flush=True)
+
+
+# ── search ────────────────────────────────────────────────────────────────────
+@app.post('/api/search')
+def search(r: SearchReq, corpus: str = MODELS):
+    index = _ready_index(corpus)
+    adapter = index.adapter
+    # Fill the facet slots the user left empty from the query text, then filter.
+    # Order matters: extraction mutates the request that build_where reads.
+    sem_q = adapter.extract_constraints(r)
+    where, args = adapter.build_where(r)
+    try:
+        if sem_q and r.sort == 'relevance':
+            total, cards = semantic_rank(
+                index.db(), index, adapter, where=where, args=args,
+                sem_q=sem_q, page=r.page, page_size=PAGE_SIZE,
+                embed_client=query_clients[corpus],
+                credential_name=QUERY_CREDENTIALS[corpus])
+        else:
+            total, cards = structured_page(
+                index.db(), index, adapter, where=where, args=args,
+                sort=r.sort, page=r.page, page_size=PAGE_SIZE)
+    except UnavailableError as e:
+        raise HTTPException(503, str(e)) from e
+    return Response(orjson.dumps({'total': total, adapter.result_key: cards}),
+                    media_type='application/json')
+
+
+@app.get('/api/facets')
+def facets(corpus: str = MODELS):
+    return Response(orjson.dumps(_ready_index(corpus).facets),
+                    media_type='application/json')
+
+
+# ── reload ────────────────────────────────────────────────────────────────────
+# publish_loop.py POSTs here after every publish so the Space picks up the new
+# index without a restart. The token gate matters: a reload checks large index
+# artifacts on the Hub and can transfer changed files, so an open endpoint would
+# let anyone burn our bandwidth on demand.
+RELOAD_TOKEN = os.environ.get('BSIDES_RELOAD_TOKEN', '')
+_reload_lock = threading.Lock()
+
+
+class ReloadReq(BaseModel):
+    token: str = ''
+
+
+@app.post('/api/reload')
+def reload_corpus(body: ReloadReq, corpus: str = MODELS):
+    """Kick off a hot-swap and answer immediately.
+
+    The download is the slow part and the caller times out at 60 s, so the
+    swap runs on a background thread; `LoadedIndex.reload` keeps the current
+    index serving until the new one has validated.
+    """
+    if not RELOAD_TOKEN:
+        raise HTTPException(
+            503, 'reload not configured: set BSIDES_RELOAD_TOKEN')
+    if not hmac.compare_digest(body.token, RELOAD_TOKEN):
+        raise HTTPException(403, 'reload token does not match')
+    try:
+        index = registry.index(corpus)
+    except KeyError:
+        raise HTTPException(404, f'unknown corpus: {corpus}') from None
+    # Non-blocking: a publish that overlaps the previous one is told to wait
+    # rather than racing a second download into the same directory.
+    if not _reload_lock.acquire(blocking=False):
+        raise HTTPException(409, 'a reload is already running')
+
+    def run() -> None:
+        try:
+            index.reload(registry.downloader)
+        finally:
+            _reload_lock.release()
+
+    threading.Thread(target=run, name=f'bsides-reload-{corpus}',
+                     daemon=True).start()
+    return {'status': 'reload started', 'corpus': corpus}
+
+
+SPREAD_SIZE = 4
+
+@app.get('/api/picks')
+def picks():
+    """The daily spread: SPREAD_SIZE cards drawn from the staff_picks.json pool,
+    rotated deterministically by UTC date — no state, fresh every midnight."""
+    index = _ready_index(MODELS)
+    adapter = index.adapter
+    picks_path = BASE / 'staff_picks.json'
+    if not picks_path.exists():
+        return Response(orjson.dumps({'picks': []}), media_type='application/json')
+    pool = orjson.loads(picks_path.read_bytes())
+    if len(pool) > SPREAD_SIZE:
+        import datetime, random
+        today = datetime.datetime.now(datetime.timezone.utc).strftime('%Y-%m-%d')
+        pool = random.Random(today).sample(pool, SPREAD_SIZE)
+    c = index.db()
+    out = []
+    for e in pool:
+        row = c.execute(
+            f'SELECT {adapter.card_columns} FROM {index.spec.table} '
+            f'WHERE {index.spec.id_column} = ?', (e['model_id'],)).fetchone()
+        if row:
+            d = adapter.card(row)
+            d['note'] = e.get('note', '')
+            d['picked_by'] = e.get('picked_by', 'staff')
+            out.append(d)
+    return Response(orjson.dumps({'picks': out}), media_type='application/json')
+
+
+@app.get('/')
+def home():
+    return FileResponse(BASE / 'static' / 'index.html')

bsides/__init__.py

@@ -0,0 +1,5 @@
+"""B-Sides collection and semantic-index pipeline."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

bsides/config.py

@@ -0,0 +1,202 @@
+"""Validated runtime settings for the B-Sides collector."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping
+
+
+PIPELINES = (
+    "text-generation",
+    "text2text-generation",
+)
+# V2 maps every model in its official text streams.  Retained as an empty
+# compatibility export for existing downstream sample tooling.
+BLACKLIST: tuple[str, ...] = ()
+
+# Listing query parameter per pipeline. The Hub's pipeline_tag=listings for
+# text2text-generation began answering HTTP 200 with an empty page (confirmed
+# 2026-08-30 in the b-sides-v2-index-2025 audit): the crawler read that as
+# stream exhaustion and dropped ~8,300 models. filter= does a tag match and
+# still enumerates the stream; the extra dual-tagged rows land under
+# text-generation too and dedupe on repo id.
+LISTING_PARAMS = {
+    "text-generation": "pipeline_tag",
+    "text2text-generation": "filter",
+}
+
+
+def _int(env: Mapping[str, str], name: str, default: int) -> int:
+    try:
+        return int(env.get(name, str(default)))
+    except ValueError as exc:
+        raise ValueError(f"{name} must be an integer") from exc
+
+
+def _float(env: Mapping[str, str], name: str, default: float) -> float:
+    try:
+        return float(env.get(name, str(default)))
+    except ValueError as exc:
+        raise ValueError(f"{name} must be a number") from exc
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    pipelines: tuple[str, ...] = PIPELINES
+    blacklist: tuple[str, ...] = BLACKLIST
+    mode: str = "both"
+    dataset_repo_id: str = "juiceb0xc0de/b-sides-v2-index"
+    run_id: str = "v2"
+    crawl_year: int | None = None
+    crawl_end: str | None = None
+    state_dir: Path = Path("/tmp/bsides")
+    hub_requests_per_window: int = 2_400
+    # Zero observes resolver traffic without proactively throttling it. Public
+    # model file fetches are not consuming the account's resolver allowance;
+    # real 429 responses are retried by HubGateway instead.
+    hub_resolver_requests_per_window: int = 0
+    hub_window_seconds: float = 300.0
+    # Fetching is latency-bound, so admitted repositories resolve concurrently.
+    fetch_workers: int = 24
+    fetch_queue_multiplier: int = 4
+    embed_workers: int = 8
+    checkpoint_interval_seconds: float = 1_800.0
+    progress_interval_seconds: float = 10.0
+    embedding_model: str = "text-embedding-3-small"
+    embedding_dimensions: int = 256
+    embedding_tokens_per_minute: int = 4_500_000
+    chunk_target_tokens: int = 1_200
+    chunk_overlap_tokens: int = 150
+    max_file_bytes: int = 2 * 1024 * 1024
+    max_repo_bytes: int = 16 * 1024 * 1024
+    checkpoint_every_repos: int = 2_500
+    tail_interval_seconds: float = 900.0
+    tail_overlap_ids: int = 100
+    lease_ttl_seconds: float = 1_800.0
+    hf_token_present: bool = False
+    openai_api_key_present: bool = False
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str]) -> "Settings":
+        settings = cls(
+            mode=env.get("BSIDES_MODE", "both").strip().lower(),
+            dataset_repo_id=env.get(
+                "BSIDES_DATASET", "juiceb0xc0de/b-sides-v2-index"
+            ).strip(),
+            run_id=env.get("BSIDES_RUN_ID", "v2").strip(),
+            crawl_year=(
+                _int(env, "BSIDES_YEAR", 0) if env.get("BSIDES_YEAR", "").strip() else None
+            ),
+            crawl_end=env.get("BSIDES_CRAWL_END", "").strip() or None,
+            state_dir=Path(env.get("BSIDES_STATE_DIR", "/tmp/bsides")),
+            hub_requests_per_window=_int(
+                env, "BSIDES_HUB_REQUESTS_PER_5M", 2_400
+            ),
+            hub_resolver_requests_per_window=_int(
+                env, "BSIDES_HUB_RESOLVER_REQUESTS_PER_5M", 0
+            ),
+            fetch_workers=_int(env, "BSIDES_FETCH_WORKERS", 24),
+            fetch_queue_multiplier=_int(
+                env, "BSIDES_FETCH_QUEUE_MULTIPLIER", 4
+            ),
+            embed_workers=_int(env, "BSIDES_EMBED_WORKERS", 8),
+            checkpoint_interval_seconds=_float(
+                env, "BSIDES_CHECKPOINT_INTERVAL_SECONDS", 1_800.0
+            ),
+            progress_interval_seconds=_float(
+                env, "BSIDES_PROGRESS_INTERVAL_SECONDS", 10.0
+            ),
+            embedding_dimensions=_int(
+                env, "BSIDES_EMBEDDING_DIMENSIONS", 256
+            ),
+            embedding_tokens_per_minute=_int(
+                env, "BSIDES_EMBEDDING_TPM", 4_500_000
+            ),
+            chunk_target_tokens=_int(
+                env, "BSIDES_CHUNK_TARGET_TOKENS", 1_200
+            ),
+            chunk_overlap_tokens=_int(
+                env, "BSIDES_CHUNK_OVERLAP_TOKENS", 150
+            ),
+            max_file_bytes=_int(env, "BSIDES_MAX_FILE_BYTES", 2 * 1024 * 1024),
+            max_repo_bytes=_int(
+                env, "BSIDES_MAX_REPO_BYTES", 16 * 1024 * 1024
+            ),
+            checkpoint_every_repos=_int(
+                env, "BSIDES_CHECKPOINT_EVERY_REPOS", 2_500
+            ),
+            tail_interval_seconds=_float(
+                env, "BSIDES_TAIL_INTERVAL_SECONDS", 900.0
+            ),
+            tail_overlap_ids=_int(env, "BSIDES_TAIL_OVERLAP_IDS", 100),
+            lease_ttl_seconds=_float(
+                env, "BSIDES_LEASE_TTL_SECONDS", 1_800.0
+            ),
+            hf_token_present=bool(env.get("HF_TOKEN", "").strip()),
+            openai_api_key_present=bool(env.get("OPENAI_API_KEY", "").strip()),
+        )
+        settings._validate()
+        return settings
+
+    def _validate(self) -> None:
+        if self.mode not in {"search", "collect", "both"}:
+            raise ValueError("BSIDES_MODE must be search, collect, or both")
+        if not 1 <= self.hub_requests_per_window < 3_000:
+            raise ValueError("Hub request budget must be between 1 and 2999")
+        if not 0 <= self.hub_resolver_requests_per_window < 20_000:
+            raise ValueError(
+                "Resolver budget must be between 0 and 19999"
+            )
+        if not 1 <= self.fetch_workers <= 64:
+            raise ValueError("fetch workers must be between 1 and 64")
+        if self.fetch_queue_multiplier <= 0:
+            raise ValueError("fetch queue multiplier must be positive")
+        if self.embed_workers <= 0:
+            raise ValueError("embedding workers must be positive")
+        if self.checkpoint_interval_seconds <= 0:
+            raise ValueError("checkpoint interval must be positive")
+        if self.progress_interval_seconds <= 0:
+            raise ValueError("progress interval must be positive")
+        if self.embedding_dimensions <= 0:
+            raise ValueError("embedding dimensions must be positive")
+        if self.embedding_tokens_per_minute <= 0:
+            raise ValueError("embedding token rate must be positive")
+        if self.chunk_target_tokens <= 0:
+            raise ValueError("chunk target must be positive")
+        if not 0 <= self.chunk_overlap_tokens < self.chunk_target_tokens:
+            raise ValueError("chunk overlap must be smaller than the target")
+        if self.max_file_bytes <= 0 or self.max_repo_bytes < self.max_file_bytes:
+            raise ValueError("artifact byte limits are inconsistent")
+        if self.checkpoint_every_repos <= 0:
+            raise ValueError("checkpoint interval must be positive")
+        if self.tail_interval_seconds <= 0:
+            raise ValueError("tail interval must be positive")
+        if self.tail_overlap_ids <= 0:
+            raise ValueError("tail overlap must be positive")
+        if self.lease_ttl_seconds <= 0:
+            raise ValueError("lease TTL must be positive")
+        if not self.dataset_repo_id:
+            raise ValueError("BSIDES_DATASET must not be empty")
+        if not self.run_id:
+            raise ValueError("BSIDES_RUN_ID must not be empty")
+        if self.crawl_year is not None and not 2000 <= self.crawl_year <= 9999:
+            raise ValueError("BSIDES_YEAR must be between 2000 and 9999")
+        if self.crawl_end is not None:
+            from datetime import datetime
+
+            try:
+                datetime.fromisoformat(self.crawl_end.replace("Z", "+00:00"))
+            except ValueError as exc:
+                raise ValueError("BSIDES_CRAWL_END must be an ISO-8601 timestamp") from exc
+
+    def validate_for_collection(self) -> None:
+        if self.mode == "search":
+            return
+        missing = []
+        if not self.hf_token_present:
+            missing.append("HF_TOKEN")
+        if not self.openai_api_key_present:
+            missing.append("OPENAI_API_KEY")
+        if missing:
+            raise ValueError("missing collection credentials: " + ", ".join(missing))

bsides/search_indexes.py

@@ -0,0 +1,1003 @@
+"""Reusable multi-corpus search index core.
+
+A corpus (models today; kernels and Docker images next) is one normalized
+embedding matrix plus one SQLite metadata table whose `row` column aligns
+1:1 with matrix rows. This module owns everything schema-agnostic:
+
+    IndexSpec        static corpus definition (dataset, table, embedding)
+    LoadedIndex      runtime state: matrix, readiness, errors, connections
+    IndexRegistry    registration, isolated loading, per-index status
+    embed_query      query embedding against one index's model/dimensions
+    semantic_rank    candidate rows → embed → score → top-k page
+    structured_page  COUNT + ORDER BY paging without embeddings
+
+Schema knowledge lives in CorpusAdapter implementations — ModelAdapter
+reproduces today's model behavior verbatim. app.py stays a thin HTTP
+layer over the registry.
+
+Loader contract: `LoadedIndex.load` never raises. A corpus that fails to
+download or validate records its error and stays not-ready; the other
+corpora keep serving.
+"""
+
+from __future__ import annotations
+
+import re
+import sqlite3
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+import numpy as np
+import orjson
+from pydantic import BaseModel, Field
+
+MATRIX_NAME = 'embeddings.f16.npy'
+SQLITE_NAME = 'meta.sqlite'
+DEFAULT_FILES = (MATRIX_NAME, SQLITE_NAME)
+
+MAX_QUERY_CHARS = 300
+PAGE_SIZE = 24
+
+
+class UnavailableError(RuntimeError):
+    """A search dependency is missing (embedding client, loaded index).
+
+    Raised from the core; the HTTP layer maps it to 503 with the message.
+    """
+
+
+@dataclass(frozen=True)
+class IndexSpec:
+    """Static definition of one searchable corpus."""
+    key: str                 # registry key: 'models' | 'kernels' | 'docker'
+    dataset_id: str          # HF dataset repo publishing the index files
+    local_dir: Path          # where the corpus files live on disk
+    table: str               # SQLite table holding the metadata rows
+    id_column: str           # human id column: 'model_id' | 'repo_id' | ...
+    embed_model: str         # embedding model used for queries
+    dimensions: int          # expected vector width; validated at load
+    files: tuple[str, ...] = DEFAULT_FILES
+
+
+
+
+def _validate_matrix(spec: IndexSpec, matrix: np.ndarray) -> None:
+    if matrix.ndim != 2:
+        raise ValueError(
+            f'{spec.key}: matrix rank {matrix.ndim} != 2')
+    if matrix.shape[1] != spec.dimensions:
+        raise ValueError(
+            f'{spec.key}: matrix has {matrix.shape[1]} dimensions, '
+            f'spec expects {spec.dimensions}')
+    if not np.isfinite(matrix).all():
+        raise ValueError(f'{spec.key}: matrix contains non-finite values')
+
+
+def _validate_sqlite(spec: IndexSpec, conn: sqlite3.Connection,
+                     matrix_rows: int) -> None:
+    quick = conn.execute('PRAGMA quick_check').fetchone()[0]
+    if quick != 'ok':
+        raise ValueError(f'{spec.key}: sqlite quick_check failed: {quick}')
+    count = conn.execute(
+        f'SELECT COUNT(*) FROM {spec.table}').fetchone()[0]
+    if count != matrix_rows:
+        raise ValueError(
+            f'{spec.key}: {count} rows in {spec.table} vs '
+            f'{matrix_rows} matrix rows')
+    if count:
+        lo, hi = conn.execute(
+            f'SELECT MIN(row), MAX(row) FROM {spec.table}').fetchone()
+        if lo < 0 or hi >= matrix_rows:
+            raise ValueError(
+                f'{spec.key}: row ids {lo}..{hi} outside matrix bounds '
+                f'0..{matrix_rows - 1}')
+
+
+class LoadedIndex:
+    """Runtime state for one corpus: matrix, readiness, connections."""
+
+    def __init__(self, spec: IndexSpec, adapter=None) -> None:
+        self.spec = spec
+        self.adapter = adapter
+        self.matrix: np.ndarray | None = None
+        self.rows: int = 0
+        self.ready = threading.Event()
+        self.error: str | None = None
+        self.facets: dict = {}
+        self.generation = 0
+        self._local = threading.local()
+
+    def db(self) -> sqlite3.Connection:
+        """Thread-local read-only connection, reopened after a swap."""
+        conn = getattr(self._local, 'conn', None)
+        if conn is not None and \
+                getattr(self._local, 'generation', -1) != self.generation:
+            # A reload swapped meta.sqlite underneath us; this connection
+            # still points at the replaced file.
+            conn.close()
+            conn = None
+        if conn is None:
+            conn = sqlite3.connect(
+                f'file:{self.spec.local_dir / SQLITE_NAME}?mode=ro', uri=True)
+            conn.row_factory = sqlite3.Row
+            self._local.conn = conn
+            self._local.generation = self.generation
+        return conn
+
+    def invalidate_connections(self) -> None:
+        """Bump the generation so every thread reopens on next db()."""
+        self.generation += 1
+
+    def load(self, downloader=None) -> None:
+        """Download-if-missing, load, validate, then flip ready.
+
+        Never raises: failure is recorded in `error` and `ready` stays
+        unset so this corpus 503s while the others keep serving.
+        Safe to call again after a failure: prior state is dropped up
+        front, so a retry can't leave ready/error disagreeing or a stale
+        matrix lingering behind the new attempt.
+        """
+        self.ready.clear()
+        self.error = None
+        self.matrix = None
+        self.rows = 0
+        self.facets = {}
+        try:
+            if not (self.spec.local_dir / MATRIX_NAME).exists():
+                if downloader is None:
+                    from huggingface_hub import snapshot_download
+                    downloader = snapshot_download
+                download_index(downloader, self.spec)
+            matrix = np.load(
+                self.spec.local_dir / MATRIX_NAME).astype(np.float32)
+            _validate_matrix(self.spec, matrix)
+            check = sqlite3.connect(
+                f'file:{self.spec.local_dir / SQLITE_NAME}?mode=ro', uri=True)
+            try:
+                _validate_sqlite(self.spec, check, matrix_rows=matrix.shape[0])
+            finally:
+                check.close()
+            self.matrix = matrix
+            self.rows = int(matrix.shape[0])
+            # A repeated load may be reading replaced files; make every
+            # thread reopen on next db() the same way a reload does.
+            self.invalidate_connections()
+            if self.adapter is not None:
+                self.facets = self.adapter.compute_facets(
+                    self.db(), self.rows)
+            self.ready.set()
+        except Exception as e:  # noqa: BLE001 — isolation is the contract
+            self.error = f'{type(e).__name__}: {e}'
+
+    def reload(self, downloader=None) -> bool:
+        """Synchronize this corpus from the Hub and hot-swap it in place.
+
+        Unlike `load`, this never skips the downloader call: the whole point is
+        to pick up a freshly published index whose files are already on disk.
+        The Hub client still uses its normal metadata diffing, so unchanged
+        artifacts are not downloaded again.
+
+        Sequenced so the slow part happens while the old index is still
+        serving — download, matrix load and validation all run first, and
+        readiness only drops for the couple of seconds it takes to swap
+        pointers and recompute facets. That is a short 503 window instead of
+        the alternative, which is answering a query against a new matrix and
+        a stale meta.sqlite and returning confidently wrong rows.
+
+        Never raises. On failure the previous matrix, facets and readiness
+        are left untouched and `error` records why: a bad publish must not
+        take search down. Returns True only when the swap completed.
+        """
+        try:
+            if downloader is None:
+                from huggingface_hub import snapshot_download
+                downloader = snapshot_download
+            download_index(downloader, self.spec)
+            matrix = np.load(
+                self.spec.local_dir / MATRIX_NAME).astype(np.float32)
+            _validate_matrix(self.spec, matrix)
+            check = sqlite3.connect(
+                f'file:{self.spec.local_dir / SQLITE_NAME}?mode=ro', uri=True)
+            try:
+                _validate_sqlite(self.spec, check, matrix_rows=matrix.shape[0])
+            finally:
+                check.close()
+        except Exception as e:  # noqa: BLE001 — keep serving the old index
+            self.error = f'reload failed: {type(e).__name__}: {e}'
+            return False
+
+        self.ready.clear()
+        try:
+            self.matrix = matrix
+            self.rows = int(matrix.shape[0])
+            # Every thread still holds a connection to the replaced file.
+            self.invalidate_connections()
+            if self.adapter is not None:
+                self.facets = self.adapter.compute_facets(self.db(), self.rows)
+            self.error = None
+        except Exception as e:  # noqa: BLE001 — matrix is valid; serve anyway
+            self.error = f'reload facets failed: {type(e).__name__}: {e}'
+        finally:
+            self.ready.set()
+        return True
+
+
+def download_index(downloader, spec: IndexSpec) -> None:
+    """Pull the corpus files from the Hub into spec.local_dir."""
+    downloader(
+        spec.dataset_id,
+        repo_type='dataset',
+        local_dir=spec.local_dir,
+        allow_patterns=list(spec.files),
+    )
+
+
+class CorpusAdapter(Protocol):
+    """Schema-specific knowledge for one corpus.
+
+    The core owns download/load/validate/rank; the adapter owns everything
+    that differs between models, kernels, and Docker images.
+    """
+    spec: IndexSpec
+    card_columns: str      # SQL select list for result cards
+    result_key: str        # response key: 'models' | 'kernels' | ...
+
+    def extract_constraints(self, req) -> str:
+        """Move structured constraints out of the request/query and into
+        the request's filter slots (never loosening explicit ones).
+        Returns the remaining text to embed; '' skips the embedding."""
+
+    def build_where(self, req) -> tuple[str, list]:
+        """SQL WHERE clause + args over this corpus's table."""
+
+    def compute_facets(self, conn: sqlite3.Connection, total: int) -> dict:
+        """Corpus-shaped facet payload served by /api/facets."""
+
+    def card(self, row: sqlite3.Row, score: float | None = None) -> dict:
+        """Serialize one metadata row into a result card."""
+
+    def sort_order(self, sort: str) -> str:
+        """ORDER BY expression for structured (non-semantic) sorts."""
+
+
+class IndexRegistry:
+    """All corpora: registration, isolated loading, per-index status."""
+
+    def __init__(self, downloader=None) -> None:
+        self._indexes: dict[str, LoadedIndex] = {}
+        self.downloader = downloader
+
+    def register(self, adapter) -> LoadedIndex:
+        index = LoadedIndex(adapter.spec, adapter)
+        self._indexes[adapter.spec.key] = index
+        return index
+
+    def index(self, key: str) -> LoadedIndex:
+        return self._indexes[key]
+
+    def keys(self) -> list[str]:
+        return list(self._indexes)
+
+    def load_all(self) -> None:
+        """Load every corpus inline; failures are isolated per index."""
+        for index in self._indexes.values():
+            index.load(self.downloader)
+
+    def start_loading(self) -> None:
+        """Load every corpus on its own background thread (boot path)."""
+        for index in self._indexes.values():
+            threading.Thread(
+                target=index.load, args=(self.downloader,),
+                name=f'bsides-load-{index.spec.key}', daemon=True).start()
+
+    def status(self) -> dict:
+        return {key: {'ready': index.ready.is_set(),
+                      'rows': index.rows,
+                      'error': index.error}
+                for key, index in self._indexes.items()}
+
+
+def embed_query(index: LoadedIndex, client, q: str, *,
+                credential_name: str = 'OPENAI_API_KEY') -> np.ndarray:
+    """Embed one query against this index's model and matrix dimensions."""
+    if client is None:
+        raise UnavailableError(
+            f'semantic search unavailable: no {credential_name}')
+    if index.matrix is None:
+        raise UnavailableError(
+            'semantic search unavailable: index not loaded')
+    resp = client.embeddings.create(
+        model=index.spec.embed_model,
+        dimensions=int(index.matrix.shape[1]),
+        input=q[:MAX_QUERY_CHARS],
+    )
+    v = np.asarray(resp.data[0].embedding, dtype=np.float32)
+    return v / max(np.linalg.norm(v), 1e-8)
+
+
+def semantic_rank(conn, index: LoadedIndex, adapter: CorpusAdapter, *,
+                  where: str, args: list, sem_q: str, page: int,
+                  page_size: int, embed_client,
+                  credential_name: str = 'OPENAI_API_KEY') -> tuple[int, list[dict]]:
+    """The relevance pipeline, corpus-agnostic.
+
+    Candidate row ids from the filtered set, one query embedding, matrix
+    scoring, argpartition top-k, then card serialization via the adapter.
+    Returns (total, cards).
+    """
+    table = index.spec.table
+    rows = np.fromiter(
+        (x[0] for x in conn.execute(
+            f'SELECT row FROM {table} WHERE {where}', args)),
+        dtype=np.int64)
+    total = len(rows)
+    if total == 0:
+        return 0, []
+    qv = embed_query(
+        index, embed_client, sem_q, credential_name=credential_name)
+    mat = index.matrix
+    scores = mat[rows] @ qv if total < index.rows // 2 else (mat @ qv)[rows]
+    want = min(total, (page + 1) * page_size)
+    top = np.argpartition(-scores, want - 1)[:want]
+    top = top[np.argsort(-scores[top])][page * page_size:]
+    if len(top) == 0:
+        return int(total), []
+    sel_rows = rows[top]
+    sel_scores = scores[top]
+    placeholders = ','.join('?' * len(sel_rows))
+    by_row = {row['row']: row for row in conn.execute(
+        f'SELECT {adapter.card_columns} FROM {table} '
+        f'WHERE row IN ({placeholders})', [int(x) for x in sel_rows])}
+    cards = [adapter.card(by_row[int(rw)], sc)
+             for rw, sc in zip(sel_rows, sel_scores)]
+    return int(total), cards
+
+
+def structured_page(conn, index: LoadedIndex, adapter: CorpusAdapter, *,
+                    where: str, args: list, sort: str, page: int,
+                    page_size: int) -> tuple[int, list[dict]]:
+    """Non-semantic path: COUNT + ORDER BY with LIMIT/OFFSET paging."""
+    table = index.spec.table
+    order = adapter.sort_order(sort)
+    total = conn.execute(
+        f'SELECT COUNT(*) FROM {table} WHERE {where}', args).fetchone()[0]
+    cur = conn.execute(
+        f'SELECT {adapter.card_columns} FROM {table} WHERE {where} '
+        f'ORDER BY {order} LIMIT ? OFFSET ?',
+        args + [page_size, page * page_size])
+    cards = [adapter.card(row) for row in cur]
+    return int(total), cards
+
+
+
+# ── models corpus ───────────────��─────────────────────────────────────────────
+# Everything below reproduces the historical single-index model behavior
+# verbatim — request shape, query-constraint parsing, SQL filtering, facet
+# computation and card serialization.
+
+MODEL_CARD_COLUMNS = ('row, model_id, author, month, downloads, likes, tags, '
+                      'base_model, relation, license, params, model_type, '
+                      'architectures, context_len, num_experts, code_imports, '
+                      'gated')
+
+MODEL_SORT_ORDERS = {
+    'newest': 'created_at DESC', 'oldest': 'created_at ASC',
+    'downloads': 'downloads DESC', 'likes': 'likes DESC',
+}
+
+MODEL_FAMILY_TERMS = {
+    'llama': ('llama',),
+    'qwen': ('qwen',),
+    'gemma': ('gemma',),
+    'mistral': ('mistral', 'mixtral'),
+    'deepseek': ('deepseek',),
+    'phi': ('phi',),
+    'granite': ('granite',),
+}
+MODEL_FAMILY_COLUMNS = (
+    'model_id', 'model_type', 'tags', 'base_model', 'architectures')
+MODEL_QUANTIZATION_MARKERS = (
+    'awq', 'gptq', 'gguf', 'ggml', 'exl2', 'exllama', 'bnb',
+    'bitsandbytes', 'hqq', 'quanto', 'aqlm', 'spqr', 'marlin',
+    'int4', '4bit', '4-bit', '8bit', '8-bit')
+
+METHOD_TAGS = ['sft', 'grpo', 'dpo', 'orpo', 'kto', 'ppo', 'lora', 'merge',
+               'unsloth', 'trl', 'axolotl', 'llama-factory', 'autotrain',
+               'custom_code']
+
+# methods a user might actually type into the query bar (skip hyphenated/internal ids)
+QUERY_METHODS = ['sft', 'grpo', 'dpo', 'orpo', 'kto', 'ppo', 'lora', 'merge',
+                 'unsloth', 'axolotl', 'autotrain']
+
+_MONTHS = {m[:3]: i for i, m in enumerate(
+    ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul',
+     'aug', 'sep', 'oct', 'nov', 'dec'], 1)}
+
+# words that carry no meaning once constraints are stripped — drop before embedding
+_STOP = {'a', 'an', 'the', 'from', 'with', 'and', 'or', 'of', 'for', 'in', 'on',
+         'to', 'at', 'by', 'that', 'this', 'is', 'are', 'has', 'have', 'than',
+         'less', 'more', 'under', 'over', 'below', 'above', 'model', 'models',
+         'params', 'param', 'downloads', 'download', 'dl', 'billion', 'b'}
+
+ARCH_TAGS = {
+    'llama', 'qwen2', 'qwen3', 'gpt2', 'mistral', 'gemma', 'gemma2', 'gemma3_text',
+    'stablelm', 'gpt_neox', 'phi', 'phi3', 'mixtral', 'falcon', 'mamba', 'mamba2',
+    'jamba', 'rwkv', 'olmo', 'olmo2', 'bloom', 'opt', 'gptj', 'gpt_bigcode',
+    'starcoder2', 'deepseek_v2', 'deepseek_v3', 'cohere', 'dbrx', 'exaone',
+    'granite', 'internlm2', 'minicpm', 'nemotron', 'persimmon', 'plamo',
+    'recurrent_gemma', 'smollm', 'xglm', 'baichuan', 'chatglm', 'yi',
+}
+
+
+class SearchReq(BaseModel):
+    query: str = ''
+    filters: dict[str, object] | None = None
+    month_from: str | None = None
+    month_to: str | None = None
+    archs: list[str] = Field(default_factory=list)
+    methods: list[str] = Field(default_factory=list)
+    relation: str | None = None
+    base_model: str | None = None     # substring match
+    author: str | None = None         # substring match
+    license: str | None = None
+    imports: list[str] = Field(default_factory=list)   # code_imports must contain all
+    params_min: int | None = None
+    params_max: int | None = None
+    context_min: int | None = None
+    downloads_min: int | None = None
+    downloads_max: int | None = None
+    moe_only: bool = False
+    custom_code_only: bool = False
+    config_contains: str | None = None  # raw substring over full config json
+    exclude_families: list[str] = Field(default_factory=list)
+    exclude_quantizations: bool = False
+    sort: str = 'relevance'             # relevance | newest | oldest | downloads | likes
+    page: int = 0
+
+
+
+def parse_query_constraints(q: str) -> tuple[dict, str]:
+    """Pull explicit hard constraints (dates, download/param ranges, methods,
+    custom-code) out of a natural-language query so they become SQL filters
+    instead of being fed to the embedder as vague semantic vibes.
+
+    Returns (extracted, remainder) where `extracted` holds SearchReq-style
+    overrides and `remainder` is the conceptual text to embed. Only the slots
+    the caller leaves empty should be filled — never loosen an explicit facet.
+    """
+    ex: dict = {}
+    work = q
+
+    # ── date: "feb 2025" (single month) else bare "2024" (whole year) ──
+    m = re.search(r'\b(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)'
+                  r'[a-z]*\.?\s+(20\d\d)\b', work)
+    if m:
+        ym = f'{m.group(2)}-{_MONTHS[m.group(1)]:02d}'
+        ex['month_from'] = ex['month_to'] = ym
+        work = work[:m.start()] + ' ' + work[m.end():]
+    else:
+        # Require a word boundary so ISO dates like 2025-05 don't have the
+        # year extracted from under the reader's feet; a full YYYY-MM string
+        # means the caller already knows the month and the parser should not
+        # widen it to the whole year.
+        m = re.search(r'\b(20\d\d)\b', work)
+        if m:
+            end = m.end()
+            if end < len(work) and work[end] == '-':
+                pass
+            else:
+                ex['month_from'] = f'{m.group(1)}-01'
+                ex['month_to'] = f'{m.group(1)}-12'
+                work = work[:m.start()] + ' ' + work[m.end():]
+
+    # ── downloads: "10-50 downloads" range, then < / > comparators (need unit) ──
+    m = re.search(r'\b(\d+)\s*(?:-|to|–|—)\s*(\d+)\s*downloads?\b', work)
+    if m:
+        ex['downloads_min'] = int(m.group(1))
+        ex['downloads_max'] = int(m.group(2))
+        work = work[:m.start()] + ' ' + work[m.end():]
+    else:
+        m = re.search(r'\b(?:less\s+than|fewer\s+than|under|below|<)\s*(\d+)\s*'
+                      r'(?:downloads?|dl|↓)\b', work)
+        if m:
+            ex['downloads_max'] = int(m.group(1)) - 1   # strict: "less than N" → < N
+            work = work[:m.start()] + ' ' + work[m.end():]
+        else:
+            m = re.search(r'\b(?:more\s+than|over|above|>)\s*(\d+)\s*'
+                          r'(?:downloads?|dl|↓)\b', work)
+            if m:
+                ex['downloads_min'] = int(m.group(1)) + 1   # strict: "more than N" → > N
+                work = work[:m.start()] + ' ' + work[m.end():]
+
+    # ── params in B: "under 3b", "<3b params", "over 7b" (needs the B suffix) ──
+    m = re.search(r'\b(?:under|less\s+than|below|<|≤)\s*(\d+(?:\.\d+)?)\s*'
+                  r'[bB](?:illion|b)?\s*(?:params?|p)?\b', work)
+    if m:
+        ex['params_max'] = int(float(m.group(1)) * 1e9)
+        work = work[:m.start()] + ' ' + work[m.end():]
+    else:
+        m = re.search(r'\b(?:over|more\s+than|above|>|≥|at\s+least)\s*(\d+(?:\.\d+)?)\s*'
+                      r'[bB](?:illion|b)?\s*(?:params?|p)?\b', work)
+        if m:
+            ex['params_min'] = int(float(m.group(1)) * 1e9)
+            work = work[:m.start()] + ' ' + work[m.end():]
+
+    # ── custom code: "custom code" / "custom-code" ──
+    if re.search(r'\bcustom[ -]?code\b', work):
+        ex['custom_code_only'] = True
+        work = re.sub(r'\bcustom[ -]?code\b', ' ', work)
+
+    # ── method tags (literal words; left in the embedding — they're meaning) ──
+    ex['methods'] = [mt for mt in QUERY_METHODS
+                     if re.search(r'\b' + re.escape(mt) + r'\b', work)]
+
+    remainder = re.sub(r'\s+', ' ', work).strip()
+    meaningful = [w for w in remainder.split() if w.lower() not in _STOP and len(w) > 2]
+    # if nothing conceptual survives, return an empty remainder so the caller
+    # skips the embedding call and just sorts the filtered set
+    return ex, (' '.join(meaningful) if meaningful else '')
+
+
+
+class ModelAdapter:
+    """The models corpus: today's single-index behavior, relocated intact."""
+
+    card_columns = MODEL_CARD_COLUMNS
+    result_key = 'models'
+
+    def __init__(self, spec: IndexSpec) -> None:
+        self.spec = spec
+
+    def extract_constraints(self, r: SearchReq) -> str:
+        """Parse the query, fill only the slots left empty, return the
+        remaining semantic text ('' skips the embedding call)."""
+        ex, sem_q = parse_query_constraints(r.query.strip())
+        if ex.get('month_from') and not r.month_from:
+            r.month_from = ex['month_from']
+        if ex.get('month_to') and not r.month_to:
+            r.month_to = ex['month_to']
+        if ex.get('downloads_min') is not None and r.downloads_min is None:
+            r.downloads_min = ex['downloads_min']
+        if ex.get('downloads_max') is not None and r.downloads_max is None:
+            r.downloads_max = ex['downloads_max']
+        if ex.get('params_min') is not None and r.params_min is None:
+            r.params_min = ex['params_min']
+        if ex.get('params_max') is not None and r.params_max is None:
+            r.params_max = ex['params_max']
+        if ex.get('custom_code_only'):
+            r.custom_code_only = True
+        for mth in ex.get('methods', []):
+            if mth not in r.methods:
+                r.methods.append(mth)
+        return sem_q
+
+    def build_where(self, r: SearchReq) -> tuple[str, list]:
+        where, args = ['1=1'], []
+        if r.month_from:
+            where.append('month >= ?'); args.append(r.month_from)
+        if r.month_to:
+            where.append('month <= ?'); args.append(r.month_to)
+        if r.archs:
+            ors = []
+            for a in r.archs:
+                ors.append('(model_type = ? OR tags LIKE ?)')
+                args += [a, f'%"{a}"%']
+            where.append('(' + ' OR '.join(ors) + ')')
+        for m in r.methods:
+            where.append('tags LIKE ?'); args.append(f'%"{m}"%')
+        if r.relation:
+            where.append('relation = ?'); args.append(r.relation)
+        if r.base_model:
+            where.append('base_model LIKE ?'); args.append(f'%{r.base_model}%')
+        if r.author:
+            where.append('author LIKE ?'); args.append(f'%{r.author}%')
+        if r.license:
+            where.append('license = ?'); args.append(r.license)
+        for imp in r.imports:
+            where.append('code_imports LIKE ?'); args.append(f'%"{imp}"%')
+        if r.params_min is not None:
+            where.append('params >= ?'); args.append(r.params_min)
+        if r.params_max is not None:
+            where.append('params <= ?'); args.append(r.params_max)
+        if r.context_min is not None:
+            where.append('context_len >= ?'); args.append(r.context_min)
+        if r.downloads_min is not None:
+            where.append('downloads >= ?'); args.append(r.downloads_min)
+        if r.downloads_max is not None:
+            where.append('downloads <= ?'); args.append(r.downloads_max)
+        if r.moe_only:
+            where.append('num_experts > 1')
+        if r.custom_code_only:
+            where.append("(code_imports IS NOT NULL OR tags LIKE '%\"custom_code\"%')")
+        if r.config_contains:
+            where.append('config LIKE ?'); args.append(f'%{r.config_contains}%')
+        for family in r.exclude_families:
+            terms = MODEL_FAMILY_TERMS.get(family.lower())
+            if not terms:
+                continue
+            family_args = []
+            rendered = []
+            for column_name in MODEL_FAMILY_COLUMNS:
+                for term in terms:
+                    rendered.append(
+                        f"LOWER(COALESCE({column_name}, '')) LIKE ?")
+                    family_args.append(f'%{term}%')
+            where.append('NOT (' + ' OR '.join(rendered) + ')')
+            args.extend(family_args)
+        if r.exclude_quantizations:
+            rendered = []
+            quant_args = []
+            for column_name in MODEL_FAMILY_COLUMNS:
+                for marker in MODEL_QUANTIZATION_MARKERS:
+                    rendered.append(
+                        f"LOWER(COALESCE({column_name}, '')) LIKE ?")
+                    quant_args.append(f'%{marker}%')
+            rendered.append(
+                "CASE WHEN json_valid(config) "
+                "THEN json_extract(config, '$.quantization_config') IS NOT NULL "
+                "ELSE 0 END")
+            where.append('NOT (' + ' OR '.join(rendered) + ')')
+            args.extend(quant_args)
+        return ' AND '.join(where), args
+
+    def sort_order(self, sort: str) -> str:
+        return MODEL_SORT_ORDERS.get(sort, 'created_at DESC')
+
+    def card(self, row: sqlite3.Row, score: float | None = None) -> dict:
+        d = dict(row)
+        d['tags'] = orjson.loads(d['tags']) if d['tags'] else []
+        d['code_imports'] = orjson.loads(d['code_imports']) if d['code_imports'] else []
+        d['architectures'] = orjson.loads(d['architectures']) if d['architectures'] else []
+        if score is not None:
+            d['score'] = round(float(score), 4)
+        return d
+
+
+    def compute_facets(self, c: sqlite3.Connection, total: int) -> dict:
+        months = [r[0] for r in c.execute(
+            'SELECT DISTINCT month FROM models ORDER BY month')]
+        licenses = [{'v': r[0], 'n': r[1]} for r in c.execute(
+            'SELECT license, COUNT(*) FROM models WHERE license IS NOT NULL '
+            'GROUP BY license ORDER BY 2 DESC LIMIT 30')]
+        relations = [{'v': r[0], 'n': r[1]} for r in c.execute(
+            'SELECT relation, COUNT(*) FROM models WHERE relation IS NOT NULL '
+            'GROUP BY relation ORDER BY 2 DESC')]
+        # Prolific authors are a real cluster axis: one person's run of regional
+        # language finetunes, one lab's architecture probes.
+        authors = [{'v': r[0], 'n': r[1]} for r in c.execute(
+            'SELECT author, COUNT(*) FROM models WHERE author IS NOT NULL '
+            'GROUP BY author ORDER BY 2 DESC LIMIT 40')]
+
+        enriched = c.execute(
+            'SELECT COUNT(*) FROM models WHERE model_type IS NOT NULL').fetchone()[0]
+        if enriched:
+            archs = [{'v': r[0], 'n': r[1]} for r in c.execute(
+                'SELECT model_type, COUNT(*) FROM models '
+                'WHERE model_type IS NOT NULL '
+                'GROUP BY model_type ORDER BY 2 DESC LIMIT 40')]
+            imports = {}
+            for (ci,) in c.execute(
+                    'SELECT code_imports FROM models '
+                    'WHERE code_imports IS NOT NULL'):
+                for mod in orjson.loads(ci):
+                    imports[mod] = imports.get(mod, 0) + 1
+            top_imports = [{'v': k, 'n': v} for k, v in
+                           sorted(imports.items(), key=lambda x: -x[1])[:40]]
+        else:
+            # pre-enrichment fallback: architecture tags from the hub tag vocabulary
+            arch_counts = {}
+            for (tags,) in c.execute('SELECT tags FROM models'):
+                for t in orjson.loads(tags):
+                    if t in ARCH_TAGS:
+                        arch_counts[t] = arch_counts.get(t, 0) + 1
+            archs = [{'v': k, 'n': v} for k, v in
+                     sorted(arch_counts.items(), key=lambda x: -x[1])[:40]]
+            top_imports = []
+
+        methods = []
+        for m in METHOD_TAGS:
+            n = c.execute('SELECT COUNT(*) FROM models WHERE tags LIKE ?',
+                          (f'%"{m}"%',)).fetchone()[0]
+            if n:
+                methods.append({'v': m, 'n': n})
+
+        return {
+            'total': total, 'months': months, 'archs': archs,
+            'methods': methods, 'licenses': licenses, 'relations': relations,
+            'imports': top_imports, 'authors': authors,
+            'enriched': bool(enriched),
+        }
+
+
+# ── kernels corpus ────────────────────────────────────────────────────────────
+
+KERNEL_CARD_COLUMNS = (
+    'row, repo_id, author, created_at, month, last_modified, downloads, '
+    'likes, tags, languages, accelerators, torch_versions, cuda_archs, '
+    'cpu_archs, operating_systems, dtypes, intrinsics, kernel_names, '
+    'torch_ops, build_variants, variant_count, has_build_dir, source_files'
+)
+
+KERNEL_JSON_COLUMNS = (
+    'tags', 'languages', 'accelerators', 'torch_versions', 'cuda_archs',
+    'cpu_archs', 'operating_systems', 'dtypes', 'intrinsics', 'kernel_names',
+    'torch_ops', 'build_variants',
+)
+
+KERNEL_ARRAY_FILTERS = (
+    'languages', 'accelerators', 'cuda_archs', 'dtypes', 'intrinsics',
+    'torch_ops', 'torch_versions',
+)
+
+KERNEL_SORT_ORDERS = {
+    'newest': 'created_at DESC', 'oldest': 'created_at ASC',
+    'downloads': 'downloads DESC', 'likes': 'likes DESC',
+}
+
+
+class KernelAdapter:
+    """Search behavior for the published kernel-repository index."""
+
+    card_columns = KERNEL_CARD_COLUMNS
+    result_key = 'kernels'
+
+    def __init__(self, spec: IndexSpec) -> None:
+        self.spec = spec
+
+    def extract_constraints(self, r: SearchReq) -> str:
+        # Kernel-specific structure is explicit in `filters`; query prose stays
+        # intact for semantic ranking instead of entering the model parser.
+        return r.query.strip()
+
+    def build_where(self, r: SearchReq) -> tuple[str, list]:
+        filters = r.filters or {}
+        where, args = ['1=1'], []
+
+        author = filters.get('author')
+        if isinstance(author, str) and author:
+            where.append('author LIKE ?')
+            args.append(f'%{author}%')
+
+        # month is stored as 'YYYY-MM' text; reject anything that is not
+        # zero-padded so a fat-fingered '2024-1' filter can't silently match
+        # nothing instead of erroring where the caller can see it.
+        for key in ('month_from', 'month_to'):
+            value = filters.get(key)
+            if value is None:
+                continue
+            if (isinstance(value, str)
+                    and re.fullmatch(r'\d{4}-(0[1-9]|1[0-2])', value)):
+                where.append(f"month {('>=', '<=')[key == 'month_to']} ?")
+                args.append(value)
+            else:
+                raise UnavailableError(
+                    f'{key} filter must be a zero-padded YYYY-MM string')
+
+        # JSON has no int type, so a UI that ships '50' as a string must not
+        # end up comparing a TEXT arg against an INTEGER column (which in
+        # SQLite never matches and returns an empty page with no error).
+        for key, column in (('downloads_min', 'downloads'),
+                            ('downloads_max', 'downloads'),
+                            ('variant_count_min', 'variant_count')):
+            value = filters.get(key)
+            if value is None:
+                continue
+            operator = '<=' if key.endswith('_max') else '>='
+            try:
+                coerced = int(value)
+            except (TypeError, ValueError) as exc:
+                raise UnavailableError(
+                    f'{key} filter must be an integer') from exc
+            where.append(f'{column} {operator} ?')
+            args.append(coerced)
+
+        for column in KERNEL_ARRAY_FILTERS:
+            selected = filters.get(column)
+            if not isinstance(selected, (list, tuple)):
+                continue
+            values = [value for value in selected
+                      if isinstance(value, str) and value]
+            if not values:
+                continue
+            placeholders = ','.join('?' * len(values))
+            where.append(
+                f'EXISTS (SELECT 1 FROM json_each(kernels.{column}) AS item '
+                f'WHERE item.value IN ({placeholders}))')
+            args.extend(values)
+
+        has_build_dir = filters.get('has_build_dir')
+        if isinstance(has_build_dir, bool):
+            where.append('has_build_dir = ?')
+            args.append(int(has_build_dir))
+
+        return ' AND '.join(where), args
+
+    def sort_order(self, sort: str) -> str:
+        return KERNEL_SORT_ORDERS.get(sort, 'created_at DESC')
+
+    def card(self, row: sqlite3.Row, score: float | None = None) -> dict:
+        card = dict(row)
+        for column in KERNEL_JSON_COLUMNS:
+            card[column] = orjson.loads(card[column]) if card[column] else []
+        card['has_build_dir'] = bool(card['has_build_dir'])
+        if score is not None:
+            card['score'] = round(float(score), 4)
+        return card
+
+    def compute_facets(self, c: sqlite3.Connection, total: int) -> dict:
+        months = [row[0] for row in c.execute(
+            'SELECT DISTINCT month FROM kernels WHERE month IS NOT NULL '
+            'ORDER BY month')]
+        authors = [{'v': row[0], 'n': row[1]} for row in c.execute(
+            'SELECT author, COUNT(*) FROM kernels WHERE author IS NOT NULL '
+            'GROUP BY author ORDER BY 2 DESC, 1 ASC LIMIT 40')]
+
+        facets = {'total': total, 'months': months, 'authors': authors}
+        for column in KERNEL_ARRAY_FILTERS:
+            counts: dict[str, int] = {}
+            for (payload,) in c.execute(
+                    f'SELECT {column} FROM kernels WHERE {column} IS NOT NULL'):
+                for value in orjson.loads(payload):
+                    counts[value] = counts.get(value, 0) + 1
+            facets[column] = [
+                {'v': value, 'n': count}
+                for value, count in sorted(
+                    counts.items(), key=lambda item: (-item[1], item[0]))
+            ]
+
+        facets['has_build_dir'] = [
+            {'v': bool(value), 'n': count}
+            for value, count in c.execute(
+                'SELECT has_build_dir, COUNT(*) FROM kernels '
+                'GROUP BY has_build_dir ORDER BY has_build_dir DESC')
+        ]
+        return facets
+
+
+# ── containers corpus ────────────────────────────────────────────────────────
+
+CONTAINER_CARD_COLUMNS = (
+    'row, repo_id, repo_type, artifact_path, artifact_kind, author, sha, '
+    'created_at, last_modified, downloads, likes, tags, description, '
+    'artifact_files, qualification_reasons, base_images, accelerators, '
+    'cuda_versions, rocm_versions, python_versions, node_versions, '
+    'operating_systems, ports, services, package_managers, frameworks, '
+    'entrypoints, commands, has_compose, has_devcontainer, has_multistage, '
+    'source_files, source_bytes'
+)
+
+CONTAINER_JSON_COLUMNS = (
+    'tags', 'artifact_files', 'qualification_reasons', 'base_images',
+    'accelerators', 'cuda_versions', 'rocm_versions', 'python_versions',
+    'node_versions', 'operating_systems', 'ports', 'services',
+    'package_managers', 'frameworks', 'entrypoints', 'commands',
+)
+
+CONTAINER_SCALAR_FILTERS = {
+    'repo_types': 'repo_type',
+    'artifact_kinds': 'artifact_kind',
+}
+
+CONTAINER_ARRAY_FILTERS = (
+    'base_images', 'accelerators', 'cuda_versions', 'rocm_versions',
+    'python_versions', 'node_versions', 'operating_systems', 'ports',
+    'services', 'package_managers', 'frameworks',
+)
+
+CONTAINER_BOOL_FILTERS = {
+    'has_compose': 'has_compose',
+    'has_devcontainer': 'has_devcontainer',
+    'has_multistage': 'has_multistage',
+}
+
+CONTAINER_SORT_ORDERS = {
+    'newest': 'created_at DESC', 'oldest': 'created_at ASC',
+    'downloads': 'downloads DESC', 'likes': 'likes DESC',
+}
+
+
+class ContainerAdapter:
+    """Search behavior for the published container-artifact index."""
+
+    card_columns = CONTAINER_CARD_COLUMNS
+    result_key = 'containers'
+
+    def __init__(self, spec: IndexSpec) -> None:
+        self.spec = spec
+
+    def extract_constraints(self, r: SearchReq) -> str:
+        return r.query.strip()
+
+    def build_where(self, r: SearchReq) -> tuple[str, list]:
+        filters = r.filters or {}
+        where, args = ['1=1'], []
+
+        for key, column in CONTAINER_SCALAR_FILTERS.items():
+            selected = filters.get(key)
+            if not isinstance(selected, (list, tuple)):
+                continue
+            values = [value for value in selected
+                      if isinstance(value, str) and value]
+            if not values:
+                continue
+            placeholders = ','.join('?' * len(values))
+            where.append(f'{column} IN ({placeholders})')
+            args.extend(values)
+
+        for column in CONTAINER_ARRAY_FILTERS:
+            selected = filters.get(column)
+            if not isinstance(selected, (list, tuple)):
+                continue
+            values = [value for value in selected
+                      if isinstance(value, (str, int)) and str(value) != '']
+            if not values:
+                continue
+            placeholders = ','.join('?' * len(values))
+            # ports are published as JSON integers; comparing the raw value
+            # against a TEXT arg via json_each never matches. Normalize both
+            # sides to text so '8888' and 8888 hit the same row.
+            compare = (f"CAST(item.value AS TEXT) IN ({placeholders})"
+                       if column == 'ports' else
+                       f'item.value IN ({placeholders})')
+            where.append(
+                f'EXISTS (SELECT 1 FROM json_each(containers.{column}) AS item '
+                f'WHERE {compare})')
+            args.extend([str(v) for v in values] if column == 'ports'
+                        else values)
+
+        for key, column in CONTAINER_BOOL_FILTERS.items():
+            value = filters.get(key)
+            if isinstance(value, bool):
+                where.append(f'{column} = ?')
+                args.append(int(value))
+
+        return ' AND '.join(where), args
+
+    def sort_order(self, sort: str) -> str:
+        return CONTAINER_SORT_ORDERS.get(sort, 'created_at DESC')
+
+    def card(self, row: sqlite3.Row, score: float | None = None) -> dict:
+        card = dict(row)
+        for column in CONTAINER_JSON_COLUMNS:
+            card[column] = orjson.loads(card[column]) if card[column] else []
+        for column in CONTAINER_BOOL_FILTERS.values():
+            card[column] = bool(card[column])
+        if score is not None:
+            card['score'] = round(float(score), 4)
+        return card
+
+    def compute_facets(self, c: sqlite3.Connection, total: int) -> dict:
+        facets = {'total': total}
+
+        for key, column in CONTAINER_SCALAR_FILTERS.items():
+            facets[key] = [
+                {'v': value, 'n': count}
+                for value, count in c.execute(
+                    f'SELECT {column}, COUNT(*) FROM containers '
+                    f'WHERE {column} IS NOT NULL '
+                    f'GROUP BY {column} ORDER BY 2 DESC, 1 ASC')
+            ]
+
+        for column in CONTAINER_ARRAY_FILTERS:
+            counts: dict[str, int] = {}
+            for (payload,) in c.execute(
+                    f'SELECT {column} FROM containers WHERE {column} IS NOT NULL'):
+                for value in orjson.loads(payload):
+                    counts[value] = counts.get(value, 0) + 1
+            facets[column] = [
+                {'v': value, 'n': count}
+                for value, count in sorted(
+                    counts.items(), key=lambda item: (-item[1], item[0]))
+            ]
+
+        for key, column in CONTAINER_BOOL_FILTERS.items():
+            facets[key] = [
+                {'v': bool(value), 'n': count}
+                for value, count in c.execute(
+                    f'SELECT {column}, COUNT(*) FROM containers '
+                    f'GROUP BY {column} ORDER BY {column} DESC')
+            ]
+
+        return facets

requirements-dev.txt

@@ -0,0 +1,5 @@
+# Local tooling only. Deliberately separate from requirements.txt so the Space
+# image does not carry build/export dependencies it never runs.
+-r requirements.txt
+pyarrow==18.1.0
+pytest==9.1.1

requirements.txt

@@ -0,0 +1,8 @@
+fastapi==0.141.1
+uvicorn[standard]==0.40.0
+numpy==2.4.2
+orjson==3.11.6
+openai==2.16.0
+huggingface_hub==1.26.0
+# not imported directly; pinned because openai and huggingface_hub both need it
+httpx==0.28.1

staff_picks.json

@@ -0,0 +1,22 @@
+[
+  {
+    "model_id": "hoanghai2110/HyperMambaLM-300M",
+    "note": "A Mamba state-space backbone with MAML-style meta-learning bolted on — built to few-shot adapt. Custom-code-only, ~300M, 11 downloads; the kind of weird SSM hybrid that never makes the charts.",
+    "picked_by": "juiceb0xc0de"
+  },
+  {
+    "model_id": "GSAI-ML/ReFusion",
+    "note": "A diffusion language model built on Qwen3-8B out of Renmin's Gaoling School — it denoises toward text instead of predicting the next token. Custom-code, 8B, and it's a mind fuck to get started.",
+    "picked_by": "juiceb0xc0de"
+  },
+  {
+    "model_id": "emozilla/LLongMA-2-7b-storysummarizer",
+    "note": "An 8K-context Llama fine-tuned on BookSum to summarize stories — a forgotten entry in the LLongMA long-context line. Custom modeling code, 5 downloads, a quiet chapter from the great context-length land grab.",
+    "picked_by": "juiceb0xc0de"
+  },
+  {
+    "model_id": "SongTonyLi/OpenELM-270M-CPT-D_chosen-HuggingFaceH4-ultrafeedback_binarized-Xlarge",
+    "note": "A 270M OpenELM run through DPO on UltraFeedback — the whole preference-tuning pipeline shrunk to pocket size. Custom-code, 2 downloads, and a repo name that won't fit on the label.",
+    "picked_by": "juiceb0xc0de"
+  }
+]

static/index.html

@@ -0,0 +1,1217 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>B-Sides — deep search for indie & vintage LLMs</title>
+<meta name="description" content="Search 228,000+ indie and vintage text-generation models on Hugging Face by meaning, time period, architecture, training method, lineage, config internals like flash_attn — the deep cuts HF search can't reach.">
+<link rel="preconnect" href="https://api.fontshare.com">
+<link href="https://api.fontshare.com/v2/css?f[]=gambarino@400&display=swap" rel="stylesheet">
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:ital,wght@0,400;0,500;0,600;1,400&display=swap" rel="stylesheet">
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/vanilla-tilt@1.8.1/dist/vanilla-tilt.min.js"></script>
+<style>
+:root {
+  /* tarot: cream parchment, sepia ink, flat pastel fills */
+  --paper: #ece2c8;
+  --card: #f6efdc;
+  --card2: #f0e7cf;
+  --ink: #3a2f22;
+  --ink-soft: #675941;
+  --ink-faint: #93835f;
+  --line: #d5c7a3;
+  --frame: #8d7a55;
+  --rose: #e9bcc4;   --rose-deep: #b25a6e;
+  --sage: #c8dcba;   --sage-deep: #5f8248;
+  --powder: #c2dbe6; --powder-deep: #4f7f96;
+  --marigold: #eed093; --marigold-deep: #a1782c;
+  --terra: #e7ab95;  --terra-deep: #ad4f36;
+  --lilac: #d7c7e7;  --lilac-deep: #7d5fa0;
+  --spring: cubic-bezier(.34,1.56,.64,1);
+  --ease: cubic-bezier(.22,.61,.36,1);
+  --serif: 'Gambarino', 'Georgia', serif;
+  --mono: 'IBM Plex Mono', monospace;
+}
+* { box-sizing: border-box; margin: 0; }
+html { scroll-behavior: smooth; }
+body { background: var(--paper); color: var(--ink); font-family: var(--mono); font-size: 14px; line-height: 1.6; min-height: 100vh; overflow-x: hidden; }
+body::after { /* paper grain */
+  content: ''; position: fixed; inset: 0; pointer-events: none; z-index: 1;
+  opacity: .05; mix-blend-mode: multiply;
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='180' height='180'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.85' numOctaves='3' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='180' height='180' filter='url(%23n)'/%3E%3C/svg%3E");
+}
+a { color: var(--terra-deep); text-decoration: none; }
+a:hover { text-decoration: underline; }
+::selection { background: var(--marigold); color: var(--ink); }
+::placeholder { color: var(--ink-faint); }
+input, select, button { font-family: inherit; font-size: inherit; color: inherit; }
+
+.wrap { position: relative; z-index: 2; max-width: 1340px; margin: 0 auto; padding: 0 26px; }
+
+/* ── header ── */
+header { display: flex; align-items: center; justify-content: space-between; padding: 16px 0; border-bottom: 1px solid var(--line); }
+.logo { display: flex; align-items: center; gap: 12px; }
+.logo-disc { width: 32px; height: 32px; border-radius: 50%; position: relative; flex: none;
+  background: var(--card); border: 1.5px solid var(--ink); }
+.logo-disc::before { content: ''; position: absolute; inset: 4px; border-radius: 50%; border: 1px solid var(--frame); }
+.logo-disc::after { content: ''; position: absolute; inset: 10px; border-radius: 50%; background: var(--terra); border: 1.5px solid var(--ink); }
+.logo h1 { font-family: var(--serif); font-weight: 400; font-size: 25px; letter-spacing: .5px; }
+.tagline { font-size: 10px; letter-spacing: 2.5px; text-transform: uppercase; color: var(--ink-faint); }
+.head-right { font-size: 11px; letter-spacing: 1px; color: var(--ink-soft); display: flex; gap: 14px; align-items: center; }
+.head-right .dot { color: var(--line); }
+
+/* ── hero: search front and center ── */
+.hero { display: flex; flex-direction: column; justify-content: center; align-items: center; text-align: center; padding: 34px 0 40px; }
+.hero h2 { font-family: var(--serif); font-weight: 400; font-size: clamp(26px, 3.4vw, 42px); line-height: 1.12; letter-spacing: .2px; max-width: 720px; }
+.hero h2 em { font-style: italic; color: var(--terra-deep); }
+.hero .rule { width: 130px; height: 10px; margin: 14px auto 22px; display: flex; gap: 5px; justify-content: center; }
+.hero .rule i { flex: 1; border-radius: 3px; }
+.searchbar { width: min(720px, 100%); display: flex; align-items: center; gap: 12px;
+  background: var(--card); border: 1.5px solid var(--ink); border-radius: 12px;
+  padding: 15px 18px; position: relative;
+  box-shadow: 4px 4px 0 rgba(58,47,34,.16);
+  transition: box-shadow .22s var(--ease), transform .22s var(--ease); }
+.searchbar:focus-within { box-shadow: 6px 7px 0 rgba(58,47,34,.20); transform: translate(-1px,-1px); }
+.searchbar .glyph { color: var(--terra-deep); font-size: 15px; }
+.searchbar input { flex: 1; background: transparent; border: none; outline: none; font-size: 15px; color: var(--ink); min-width: 40px; }
+.corpus-select { flex: none; background: var(--card2); border: 1px solid var(--frame); border-radius: 8px;
+  padding: 7px 28px 7px 10px; outline: none; font-size: 11px; font-weight: 600;
+  letter-spacing: 1.5px; text-transform: uppercase; cursor: pointer; }
+.corpus-select:focus { border-color: var(--ink); }
+@media (max-width: 620px) {
+  .searchbar { gap: 8px; padding: 12px; flex-wrap: wrap; }
+  .searchbar .glyph { display: none; }
+  .corpus-select { order: 1; }
+  .searchbar input { order: 2; width: calc(100% - 118px); }
+  .btn-dig { order: 3; margin-left: auto; }
+}
+.btn-dig { border: 1.5px solid var(--ink); cursor: pointer; white-space: nowrap;
+  font-size: 11px; font-weight: 600; letter-spacing: 2px; text-transform: uppercase;
+  color: var(--ink); background: var(--marigold); border-radius: 9px; padding: 9px 18px;
+  box-shadow: 3px 3px 0 var(--ink);
+  transition: transform .15s var(--spring), box-shadow .15s var(--spring); }
+.btn-dig:hover { transform: translate(-1px,-2px); box-shadow: 4px 5px 0 var(--ink); }
+.btn-dig:active { transform: translate(3px,3px); box-shadow: 0 0 0 var(--ink); }
+.status-line { margin-top: 14px; font-size: 12.5px; color: var(--ink-soft); min-height: 20px; }
+.status-line b { color: var(--terra-deep); font-weight: 600; }
+.hero .promise { margin-top: 6px; font-size: 11.5px; color: var(--ink-faint); letter-spacing: .4px; max-width: 640px; }
+.hero .promise b { color: var(--ink-soft); font-weight: 500; }
+.hero .manifesto { margin-top: 18px; max-width: 620px; font-family: var(--serif); font-size: 14px; line-height: 1.62; color: var(--ink-soft); }
+
+/* ── layout ── */
+.main { display: grid; grid-template-columns: 262px 1fr; gap: 30px; padding: 22px 0 80px; }
+@media (max-width: 900px) { .main { grid-template-columns: 1fr; } }
+
+/* rail */
+.rail { position: sticky; top: 14px; align-self: start; display: flex; flex-direction: column; gap: 14px; max-height: calc(100vh - 28px); overflow-y: auto; scrollbar-width: thin; padding: 4px 8px 24px 4px; }
+@media (max-width: 900px) { .rail { position: static; max-height: none; } }
+.filter-stack { display: flex; flex-direction: column; gap: 14px; }
+.knob-group { border: 1.5px solid var(--ink); border-radius: 11px; background: var(--card); padding: 13px 14px; box-shadow: 3px 3px 0 rgba(58,47,34,.12); }
+.knob-group h4 { font-size: 10px; letter-spacing: 2.5px; text-transform: uppercase; margin-bottom: 10px; font-weight: 600; color: var(--ink); display: flex; align-items: center; gap: 8px; }
+.knob-group h4 .swatch { width: 22px; height: 8px; border-radius: 3px; border: 1px solid var(--ink); flex: none; }
+.knob-group h4 .soon { margin-left: auto; color: var(--ink-faint); border: 1px dashed var(--frame); border-radius: 6px; padding: 1px 7px; letter-spacing: 1px; font-size: 9px; text-transform: none; }
+.chips { display: flex; flex-wrap: wrap; gap: 6px; }
+.chip { cursor: pointer; user-select: none; font-size: 11.5px; padding: 3.5px 10px; border-radius: 999px;
+  border: 1px solid var(--frame); color: var(--ink-soft); background: transparent;
+  transition: transform .16s var(--spring), background .16s, color .16s, border-color .16s; }
+.chip:hover { border-color: var(--ink); color: var(--ink); transform: translateY(-1px); }
+.chip .n { opacity: .55; font-size: 10px; margin-left: 4px; }
+.chip.more-toggle { border-style: dashed; }
+.chip.on { border-color: var(--ink); color: var(--ink); font-weight: 600; box-shadow: 2px 2px 0 rgba(58,47,34,.25); }
+.kg-arch .chip.on { background: var(--marigold); }
+.kg-method .chip.on { background: var(--sage); }
+.kg-deep .chip.on { background: var(--lilac); }
+.kg-kernel .chip.on { background: var(--chip-fill, var(--powder)); }
+.rail select, .rail input[type=text], .rail input[type=number] {
+  width: 100%; background: #fbf6e8; border: 1px solid var(--frame); border-radius: 8px;
+  padding: 7px 10px; outline: none; font-size: 12.5px; color: var(--ink); transition: border-color .2s; }
+.rail select:focus, .rail input:focus { border-color: var(--ink); }
+.range-row { display: flex; gap: 8px; align-items: center; }
+.range-row span { color: var(--ink-faint); font-size: 11px; }
+.toggle-row { display: flex; align-items: center; justify-content: space-between; margin-top: 9px; font-size: 12.5px; color: var(--ink-soft); cursor: pointer; user-select: none; }
+.switch { width: 34px; height: 19px; border-radius: 999px; background: #fbf6e8; border: 1px solid var(--frame); position: relative; transition: background .2s; flex: none; }
+.switch::after { content: ''; position: absolute; top: 2px; left: 2px; width: 13px; height: 13px; border-radius: 50%; background: var(--ink-faint); transition: all .2s var(--spring); }
+.toggle-row.on .switch { background: var(--lilac); border-color: var(--ink); }
+.toggle-row.on .switch::after { left: 17px; background: var(--ink); }
+.sub-label { font-size: 10px; letter-spacing: 1.6px; text-transform: uppercase; color: var(--ink-soft); margin-bottom: 7px; }
+.sub-label .hint { text-transform: none; letter-spacing: .3px; color: var(--ink-faint); }
+.warn { margin-top: 7px; font-size: 11px; color: var(--terra-deep); }
+.excludes { display: flex; flex-direction: column; gap: 3px; }
+.ex-row { display: flex; align-items: center; gap: 8px; font-size: 12.5px; color: var(--ink-soft); cursor: pointer; user-select: none; }
+.ex-row .box { width: 14px; height: 14px; flex: none; border-radius: 4px; border: 1px solid var(--frame); background: #fbf6e8; position: relative; transition: background .16s, border-color .16s; }
+.ex-row.on { color: var(--ink); }
+.ex-row.on .box { background: var(--terra); border-color: var(--ink); }
+.ex-row.on .box::after { content: '✕'; position: absolute; inset: 0; font-size: 10px; line-height: 13px; text-align: center; color: var(--ink); }
+.exclude-note { margin-top: 9px; font-size: 10.5px; line-height: 1.5; color: var(--ink-faint); }
+.tcard.docker-card .mid { word-break: break-word; font-size: 16px; }
+.tcard.docker-card .pills { max-height: 54px; overflow: hidden; }
+.tcard.docker-card .facts { margin-top: 9px; font-size: 10px; color: var(--ink-faint); letter-spacing: .5px; word-break: break-all; }
+.btn-clear { width: 100%; cursor: pointer; background: transparent; border: 1px dashed var(--frame); border-radius: 10px; padding: 8px; color: var(--ink-faint); font-size: 11px; letter-spacing: 2px; text-transform: uppercase; transition: all .2s; }
+.btn-clear:hover { border-color: var(--terra-deep); color: var(--terra-deep); }
+
+/* section heads */
+.crates-head { display: flex; align-items: baseline; justify-content: space-between; margin: 6px 0 16px; flex-wrap: wrap; gap: 10px; }
+.crates-head h3 { font-family: var(--serif); font-weight: 400; font-size: 26px; }
+.crates-head .sub { font-size: 11px; color: var(--ink-faint); letter-spacing: 1px; }
+.sort-row { display: flex; gap: 8px; align-items: center; font-size: 11.5px; color: var(--ink-soft); }
+.sort-row select { background: #fbf6e8; border: 1px solid var(--frame); border-radius: 8px; padding: 5px 9px; font-size: 11.5px; color: var(--ink); outline: none; }
+
+/* ── the spread (staff picks) ── */
+#spread { margin-bottom: 34px; }
+.spread-row { display: grid; grid-template-columns: repeat(auto-fill, minmax(230px, 1fr)); gap: 20px; }
+.pick { text-align: center; }
+.pick .note { margin-top: 10px; font-family: var(--serif); font-style: italic; font-size: 13.5px; color: var(--ink-soft); line-height: 1.5; padding: 0 6px; }
+.pick .by { margin-top: 4px; font-size: 10px; letter-spacing: 1.5px; text-transform: uppercase; color: var(--ink-faint); }
+
+/* ── tarot card ── */
+.grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); gap: 20px; }
+.tcard { position: relative; cursor: pointer; border-radius: 12px; overflow: hidden;
+  background: var(--card); border: 1.5px solid var(--ink);
+  box-shadow: 3px 4px 0 rgba(58,47,34,.14);
+  transition: transform .22s var(--spring), box-shadow .25s var(--ease);
+  transform-style: preserve-3d; }
+.tcard::after { /* inner frame */
+  content: ''; position: absolute; inset: 5px; border: 1px solid var(--frame); border-radius: 8px; pointer-events: none; }
+.tcard:hover { transform: translateY(-4px) rotate(-.5deg); box-shadow: 5px 9px 0 rgba(58,47,34,.18); }
+.tcard .sky { /* pastel top band */
+  background: var(--tc, var(--powder)); border-bottom: 1px solid var(--ink);
+  padding: 7px 14px 6px; display: flex; justify-content: space-between; align-items: center;
+  font-size: 10px; letter-spacing: 2px; color: var(--ink); }
+.tcard .sky .num { font-weight: 600; }
+.tcard .body { padding: 14px 15px 12px; text-align: center; }
+.tcard .mid { font-family: var(--serif); font-size: 17.5px; line-height: 1.25; word-break: break-all; }
+.tcard .author { font-size: 10.5px; color: var(--ink-faint); letter-spacing: 1px; margin-top: 3px; }
+.tcard .meta { display: flex; gap: 9px; justify-content: center; margin-top: 9px; font-size: 10.5px; color: var(--ink-soft); flex-wrap: wrap; }
+.tcard .meta .sc-match { color: var(--terra-deep); font-weight: 600; }
+.tcard .pills { display: flex; flex-wrap: wrap; gap: 5px; justify-content: center; margin-top: 9px; min-height: 0; }
+.tcard .pill { font-size: 9.5px; padding: 1.5px 8px; border-radius: 999px; border: 1px solid var(--ink); background: var(--pc, var(--sage)); color: var(--ink); }
+.tcard .pill.hot { background: var(--terra); font-weight: 600; }
+.tcard .lineage { margin-top: 8px; font-size: 10px; color: var(--ink-faint); font-style: italic; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.tcard .caption { border-top: 1px solid var(--ink); margin-top: 11px; padding: 7px 10px 8px;
+  font-size: 10px; letter-spacing: 2.5px; text-transform: uppercase; color: var(--ink);
+  background: var(--card2); position: relative; z-index: 0; }
+.tcard.kernel-card .mid { word-break: break-word; }
+.tcard.kernel-card .pills { max-height: 54px; overflow: hidden; }
+.tcard.kernel-card .facts { margin-top: 9px; font-size: 10px; color: var(--ink-faint); letter-spacing: .5px; }
+
+/* loader: ink-drawn spinning card */
+.loader { display: none; margin: 46px auto; width: 46px; height: 66px; border-radius: 7px;
+  background: var(--card); border: 1.5px solid var(--ink); position: relative;
+  animation: flip 1s var(--ease) infinite; }
+.loader::after { content: ''; position: absolute; inset: 5px; border: 1px solid var(--frame); border-radius: 4px; }
+@keyframes flip { 0%{transform:rotateY(0)} 50%{transform:rotateY(180deg)} 100%{transform:rotateY(360deg)} }
+.loading .loader { display: block; }
+.loading .grid, .loading .spread-row { opacity: .35; }
+
+.empty { text-align: center; padding: 60px 0; display: none; }
+.empty .kao { font-size: 26px; color: var(--terra-deep); letter-spacing: 2px; }
+.empty h4 { font-family: var(--serif); font-size: 27px; margin-top: 12px; }
+.empty p { color: var(--ink-faint); margin-top: 8px; font-size: 13px; }
+
+.btn-more { display: block; margin: 30px auto 0; cursor: pointer;
+  background: var(--card); border: 1.5px solid var(--ink); border-radius: 999px;
+  color: var(--ink); padding: 10px 30px; font-size: 11px; letter-spacing: 2.5px; text-transform: uppercase;
+  box-shadow: 3px 3px 0 rgba(58,47,34,.18);
+  transition: transform .18s var(--spring), box-shadow .18s var(--spring); }
+.btn-more:hover { transform: translate(-1px,-2px); box-shadow: 4px 5px 0 rgba(58,47,34,.22); }
+.btn-more:active { transform: translate(3px,3px); box-shadow: 0 0 0 rgba(58,47,34,.2); }
+
+footer { border-top: 1px solid var(--line); padding: 22px 0 52px;
+  display: flex; justify-content: space-between; flex-wrap: wrap; gap: 12px;
+  font-size: 11.5px; color: var(--ink-faint); letter-spacing: .8px; }
+footer .next { color: var(--marigold-deep); }
+</style>
+</head>
+<body>
+<div class="wrap">
+
+  <header id="hdr">
+    <div class="logo">
+      <div class="logo-disc"></div>
+      <div>
+        <h1>B-Sides.</h1>
+        <div class="tagline" id="tagline">deep search · indie & vintage LLMs</div>
+      </div>
+    </div>
+    <div class="head-right">
+      <span>🤗 hugging face space</span><span class="dot">|</span><span id="head-count">…</span><span class="dot">|</span><span id="catalog-copy">2022 pressing</span>
+    </div>
+  </header>
+
+  <div class="main">
+    <aside class="rail" id="rail">
+
+      <div class="filter-stack" id="model-filters">
+
+      <div class="knob-group kg-exclude" id="exclude-group">
+        <h4><span class="swatch" style="background:var(--terra)"></span>Hidden by default</h4>
+        <div class="excludes" id="f-excludes"></div>
+        <p class="exclude-note">checked is hidden · uncheck to let them back into the crates</p>
+      </div>
+
+      <div class="knob-group kg-time">
+        <h4><span class="swatch" style="background:var(--rose)"></span>Time period</h4>
+        <div class="range-row">
+          <select id="f-month-from"></select><span>→</span><select id="f-month-to"></select>
+        </div>
+      </div>
+
+      <div class="knob-group kg-arch">
+        <h4><span class="swatch" style="background:var(--marigold)"></span>Architecture</h4>
+        <div class="chips" id="f-archs"></div>
+      </div>
+
+      <div class="knob-group kg-method">
+        <h4><span class="swatch" style="background:var(--sage)"></span>Training method</h4>
+        <div class="chips" id="f-methods"></div>
+      </div>
+
+      <div class="knob-group kg-lineage">
+        <h4><span class="swatch" style="background:var(--powder)"></span>Lineage</h4>
+        <select id="f-relation"><option value="">any relation</option></select>
+        <div style="height:8px"></div>
+        <input id="f-base" type="text" placeholder="base model contains…">
+      </div>
+
+      <div class="knob-group kg-license">
+        <h4><span class="swatch" style="background:var(--terra)"></span>License</h4>
+        <select id="f-license"><option value="">any license</option></select>
+      </div>
+
+      <div class="knob-group kg-deep" id="deep-group">
+        <h4><span class="swatch" style="background:var(--lilac)"></span>Deep cuts <span class="soon" id="deep-soon" style="display:none">pressing…</span></h4>
+        <div id="deep-filters">
+          <div class="sub-label">Model size (billions) <span class="hint">e.g. 1.5B–3.5B</span></div>
+          <div class="range-row">
+            <input id="f-pmin" type="number" placeholder="params ≥ (B)" step="0.1" min="0">
+            <input id="f-pmax" type="number" placeholder="≤ (B)" step="0.1" min="0">
+          </div>
+          <div class="warn" id="size-warn" style="display:none">minimum is above maximum</div>
+          <div style="height:8px"></div>
+          <input id="f-ctx" type="number" placeholder="context ≥ tokens">
+          <div style="height:8px"></div>
+          <input id="f-config" type="text" placeholder='config contains… "rope_scaling"'>
+          <div style="height:10px"></div>
+          <div class="chips" id="f-imports"></div>
+        </div>
+        <div class="toggle-row" id="f-moe"><span>MoE only</span><span class="switch"></span></div>
+        <div class="toggle-row" id="f-custom"><span>custom code only</span><span class="switch"></span></div>
+      </div>
+
+      </div>
+
+      <div class="filter-stack" id="kernel-filters" style="display:none">
+        <div class="knob-group kg-time">
+          <h4><span class="swatch" style="background:var(--rose)"></span>Time period</h4>
+          <div class="range-row">
+            <select id="k-month-from"></select><span>→</span><select id="k-month-to"></select>
+          </div>
+        </div>
+
+        <div class="knob-group kg-kernel" style="--chip-fill:var(--rose)">
+          <h4><span class="swatch" style="background:var(--rose)"></span>Downloads</h4>
+          <div class="range-row">
+            <input id="k-downloads-min" type="number" placeholder="downloads ≥" min="0">
+            <input id="k-downloads-max" type="number" placeholder="≤" min="0">
+          </div>
+        </div>
+
+        <div class="knob-group kg-kernel" style="--chip-fill:var(--marigold)">
+          <h4><span class="swatch" style="background:var(--marigold)"></span>Languages</h4>
+          <div class="chips" id="k-languages"></div>
+        </div>
+
+        <div class="knob-group kg-kernel" style="--chip-fill:var(--sage)">
+          <h4><span class="swatch" style="background:var(--sage)"></span>Accelerators</h4>
+          <div class="chips" id="k-accelerators"></div>
+        </div>
+
+        <div class="knob-group kg-kernel" style="--chip-fill:var(--powder)">
+          <h4><span class="swatch" style="background:var(--powder)"></span>CUDA architectures</h4>
+          <div class="chips" id="k-cuda-archs"></div>
+        </div>
+
+        <div class="knob-group kg-kernel" style="--chip-fill:var(--lilac)">
+          <h4><span class="swatch" style="background:var(--lilac)"></span>Dtypes</h4>
+          <div class="chips" id="k-dtypes"></div>
+        </div>
+
+        <div class="knob-group kg-kernel" style="--chip-fill:var(--terra)">
+          <h4><span class="swatch" style="background:var(--terra)"></span>Intrinsics</h4>
+          <div class="chips" id="k-intrinsics"></div>
+        </div>
+
+        <div class="knob-group kg-kernel" style="--chip-fill:var(--marigold)">
+          <h4><span class="swatch" style="background:var(--marigold)"></span>Torch operations</h4>
+          <div class="chips" id="k-torch-ops"></div>
+        </div>
+
+        <div class="knob-group kg-kernel" style="--chip-fill:var(--sage)">
+          <h4><span class="swatch" style="background:var(--sage)"></span>Torch versions</h4>
+          <div class="chips" id="k-torch-versions"></div>
+        </div>
+
+        <div class="knob-group kg-kernel">
+          <h4><span class="swatch" style="background:var(--powder)"></span>Author</h4>
+          <select id="k-author"><option value="">any author</option></select>
+        </div>
+
+        <div class="knob-group kg-kernel">
+          <h4><span class="swatch" style="background:var(--lilac)"></span>Minimum variants</h4>
+          <input id="k-variant-min" type="number" placeholder="variants ≥" min="0">
+        </div>
+
+        <div class="knob-group kg-kernel">
+          <h4><span class="swatch" style="background:var(--terra)"></span>Build facts</h4>
+          <div class="toggle-row" id="k-build"><span>has build directory</span><span class="switch"></span></div>
+        </div>
+      </div>
+
+      <div class="filter-stack" id="docker-filters" style="display:none">
+        <div class="knob-group kg-kernel" style="--chip-fill:var(--terra)">
+          <h4><span class="swatch" style="background:var(--terra)"></span>Artifact kind</h4>
+          <div class="toggle-row" id="d-archives"><span>include archives</span><span class="switch"></span></div>
+          <p class="exclude-note">recipes only by default · archives are tarballs, not build files</p>
+        </div>
+
+        <div class="knob-group kg-kernel" style="--chip-fill:var(--rose)">
+          <h4><span class="swatch" style="background:var(--rose)"></span>Repository type</h4>
+          <div class="chips" id="d-repo-types"></div>
+        </div>
+
+        <div class="knob-group kg-kernel" style="--chip-fill:var(--sage)">
+          <h4><span class="swatch" style="background:var(--sage)"></span>Accelerators</h4>
+          <div class="chips" id="d-accelerators"></div>
+        </div>
+
+        <div class="knob-group kg-kernel" style="--chip-fill:var(--powder)">
+          <h4><span class="swatch" style="background:var(--powder)"></span>CUDA versions</h4>
+          <div class="chips" id="d-cuda-versions"></div>
+        </div>
+
+        <div class="knob-group kg-kernel" style="--chip-fill:var(--terra)">
+          <h4><span class="swatch" style="background:var(--terra)"></span>ROCm versions</h4>
+          <div class="chips" id="d-rocm-versions"></div>
+        </div>
+
+        <div class="knob-group kg-kernel" style="--chip-fill:var(--marigold)">
+          <h4><span class="swatch" style="background:var(--marigold)"></span>Python versions</h4>
+          <div class="chips" id="d-python-versions"></div>
+        </div>
+
+        <div class="knob-group kg-kernel" style="--chip-fill:var(--lilac)">
+          <h4><span class="swatch" style="background:var(--lilac)"></span>Frameworks</h4>
+          <div class="chips" id="d-frameworks"></div>
+        </div>
+
+        <div class="knob-group kg-kernel" style="--chip-fill:var(--sage)">
+          <h4><span class="swatch" style="background:var(--sage)"></span>Base images</h4>
+          <div class="chips" id="d-base-images"></div>
+        </div>
+
+        <div class="knob-group kg-kernel" style="--chip-fill:var(--powder)">
+          <h4><span class="swatch" style="background:var(--powder)"></span>Operating systems</h4>
+          <div class="chips" id="d-operating-systems"></div>
+        </div>
+
+        <div class="knob-group kg-kernel" style="--chip-fill:var(--marigold)">
+          <h4><span class="swatch" style="background:var(--marigold)"></span>Package managers</h4>
+          <div class="chips" id="d-package-managers"></div>
+        </div>
+
+        <div class="knob-group kg-kernel" style="--chip-fill:var(--rose)">
+          <h4><span class="swatch" style="background:var(--rose)"></span>Services</h4>
+          <div class="chips" id="d-services"></div>
+        </div>
+
+        <div class="knob-group kg-kernel" style="--chip-fill:var(--lilac)">
+          <h4><span class="swatch" style="background:var(--lilac)"></span>Node versions</h4>
+          <div class="chips" id="d-node-versions"></div>
+        </div>
+
+        <!-- No exposed-ports control: ports are published as JSON integers and
+             the adapter only accepts string filter values, so any chip here
+             would match nothing. Needs a backend cast before it ships. -->
+
+        <div class="knob-group kg-kernel">
+          <h4><span class="swatch" style="background:var(--powder)"></span>Build facts</h4>
+          <div class="toggle-row" id="d-compose"><span>has compose file</span><span class="switch"></span></div>
+          <div class="toggle-row" id="d-devcontainer"><span>has devcontainer</span><span class="switch"></span></div>
+          <div class="toggle-row" id="d-multistage"><span>multi-stage build</span><span class="switch"></span></div>
+        </div>
+      </div>
+
+      <button class="btn-clear" id="clear">✕ clear the deck</button>
+    </aside>
+
+    <section>
+      <section class="hero">
+        <h2 id="hero-h">The models that never charted.<br><em>Dig anyway.</em></h2>
+        <div class="rule" id="rule">
+          <i style="background:var(--rose)"></i><i style="background:var(--marigold)"></i>
+          <i style="background:var(--sage)"></i><i style="background:var(--powder)"></i>
+          <i style="background:var(--lilac)"></i>
+        </div>
+        <div class="searchbar" id="term">
+          <span class="glyph">✦</span>
+          <select class="corpus-select" id="corpus" aria-label="Search corpus">
+            <option value="models" selected>Models</option>
+            <option value="kernels">Kernels</option>
+            <option value="docker">Docker Images</option>
+          </select>
+          <input id="q" type="text" placeholder='search by meaning… "mamba hybrid trained on code"' autocomplete="off">
+          <button class="btn-dig" id="go">dig ⏵</button>
+        </div>
+        <div class="status-line" id="status"></div>
+        <p class="promise" id="promise"><b id="hero-count">228,610</b> indie & vintage text-gen models · no chart-toppers, no quant reissues ·
+          search by <b>meaning</b>, <b>time period</b>, <b>lineage</b>, or straight into the <b>config</b></p>
+        <p class="manifesto" id="manifesto">B-Sides index is more interesting than &ldquo;models nobody uses.&rdquo;
+          It maps the shadow infrastructure of open ML: abandoned experiments, regional
+          language work, architecture probes, creative utilities, and research releases that
+          conventional popularity rankings erase.</p>
+      </section>
+
+      <div id="spread" style="display:none">
+        <div class="crates-head">
+          <h3>The Spread.</h3>
+          <span class="sub">today's draw · rotates at midnight UTC</span>
+        </div>
+        <div class="spread-row" id="spread-row"></div>
+      </div>
+
+      <div class="crates-head" id="crates-head" style="display:none">
+        <h3 id="crate-title">The Reading.</h3>
+        <div class="sort-row">
+          sort
+          <select id="sort">
+            <option value="relevance">relevance</option>
+            <option value="newest" selected>newest</option>
+            <option value="oldest">oldest</option>
+            <option value="downloads">downloads</option>
+            <option value="likes">likes</option>
+          </select>
+        </div>
+      </div>
+      <div id="results-wrap">
+        <div class="grid" id="grid"></div>
+        <div class="loader"></div>
+        <div class="empty" id="empty">
+          <div class="kao">ᕦ(ˇò_ó)ᕤ︻╦╤─</div>
+          <h4 id="empty-title">The cards are silent.</h4>
+          <p id="empty-copy">no record answers to that. loosen a filter or flip the query.</p>
+        </div>
+        <button class="btn-more" id="more" style="display:none">⏬ dig deeper</button>
+      </div>
+    </section>
+  </div>
+
+  <footer>
+    <span id="footer-main">pressed by <a href="https://huggingface.co/juiceb0xc0de" target="_blank">juiceb0xc0de</a> · slop-free: no quant reissues, no chart-toppers</span>
+    <span class="next" id="footer-next">next pressings: 2024 catalog · config-deep filters</span>
+  </footer>
+</div>
+
+<script>
+'use strict';
+const $ = id => document.getElementById(id);
+/* product defaults: the crates hide the majors and the quant reissues unless
+   the digger says otherwise. Checked in the UI means hidden from results. */
+const DEFAULT_EXCLUDED_FAMILIES = ['llama','qwen','gemma','mistral','deepseek','phi','granite'];
+const FAMILY_LABELS = {
+  llama: 'Llama', qwen: 'Qwen', gemma: 'Gemma', mistral: 'Mistral/Mixtral',
+  deepseek: 'DeepSeek', phi: 'Phi', granite: 'Granite',
+};
+/* mirrors CONTAINER_ARRAY_FILTERS server-side; each is its own AND group */
+const DOCKER_ARRAY_FILTERS = ['base_images','accelerators','cuda_versions','rocm_versions',
+  'python_versions','node_versions','operating_systems','ports','services',
+  'package_managers','frameworks'];
+const DOCKER_BOOL_FILTERS = ['has_compose','has_devcontainer','has_multistage'];
+
+const state = {
+  corpus: 'models', page: 0, total: 0, busy: false, epoch: 0,
+  facets: { models: null, kernels: null, docker: null },
+  ready: { models: false, kernels: false, docker: false },
+  loading: { models: null, kernels: null, docker: null },
+  sel: {
+    models: {
+      archs: new Set(), methods: new Set(), imports: new Set(), moe: false, custom: false,
+      excludedFamilies: new Set(DEFAULT_EXCLUDED_FAMILIES),
+      excludeQuantizations: true,
+    },
+    kernels: {
+      languages: new Set(), accelerators: new Set(), cuda_archs: new Set(),
+      dtypes: new Set(), intrinsics: new Set(), torch_ops: new Set(),
+      torch_versions: new Set(), has_build_dir: false,
+    },
+    docker: {
+      repo_types: new Set(),
+      ...Object.fromEntries(DOCKER_ARRAY_FILTERS.map(k => [k, new Set()])),
+      has_compose: false, has_devcontainer: false, has_multistage: false,
+      includeArchives: false,
+    },
+  },
+};
+
+const resultKey = {models:'models', kernels:'kernels', docker:'containers'};
+const endpoint = (kind, corpus) => corpus === 'models'
+  ? `/api/${kind}` : `/api/${kind}?corpus=${encodeURIComponent(corpus)}`;
+/* card renderers are hoisted function declarations, so this map is safe here */
+const CARD_RENDERERS = {models: tarotCard, kernels: kernelCard, docker: dockerCard};
+const WARMING = {
+  models: 'warming the model crates…', kernels: 'warming the kernel crates…',
+  docker: 'warming the container crates…',
+};
+const IDLE_NOUNS = {
+  models: 'models in the crates', kernels: 'kernel repositories indexed',
+  docker: 'container artifacts indexed',
+};
+const RESULT_NOUNS = {models: 'models', kernels: 'kernels', docker: 'container artifacts'};
+const HEAD_NOUNS = {models: 'models', kernels: 'kernels', docker: 'artifacts'};
+const CRATE_TITLES = {
+  models: 'The Reading.', kernels: 'The Kernel Cut.', docker: 'The Build Sheet.',
+};
+
+const COPY = {
+  models: {
+    title: 'B-Sides — deep search for indie & vintage LLMs',
+    description: 'Search indie and vintage text-generation models on Hugging Face by meaning, time period, architecture, training method, lineage, and config internals.',
+    tagline: 'deep search · indie & vintage LLMs',
+    hero: 'The models that never charted.<br><em>Dig anyway.</em>',
+    placeholder: 'search by meaning… "mamba hybrid trained on code"',
+    promise: total => `<b id="hero-count">${total}</b> indie & vintage text-gen models · the majors and quant reissues are <b>hidden by default</b> — uncheck any of them in the rail to let them back in · search by <b>meaning</b>, <b>time period</b>, <b>lineage</b>, or straight into the <b>config</b>`,
+    manifesto: 'B-Sides index is more interesting than &ldquo;models nobody uses.&rdquo; It maps the shadow infrastructure of open ML: abandoned experiments, regional language work, architecture probes, creative utilities, and research releases that conventional popularity rankings erase.',
+    emptyTitle: 'The cards are silent.',
+    emptyCopy: 'no record answers to that. loosen a filter or flip the query.',
+    footer: 'pressed by <a href="https://huggingface.co/juiceb0xc0de" target="_blank">juiceb0xc0de</a> · slop-free: no quant reissues, no chart-toppers',
+    next: 'next pressings: 2024 catalog · config-deep filters',
+    catalog: '2022 pressing',
+  },
+  kernels: {
+    title: 'B-Sides — deep search for open ML kernels',
+    description: 'Search open ML kernel repositories on Hugging Face by meaning, language, accelerator, CUDA architecture, dtype, intrinsic, Torch operation, and build facts.',
+    tagline: 'deep search · open ML kernels',
+    hero: 'The kernels beneath the charts.<br><em>Dig deeper.</em>',
+    placeholder: 'search by meaning… "fused attention for Hopper"',
+    promise: total => `<b id="hero-count">${total}</b> open ML kernel repositories · search by <b>meaning</b>, <b>hardware path</b>, <b>dtype</b>, or <b>build facts</b>`,
+    manifesto: 'The kernel crates map the code beneath model releases: CUDA and Triton experiments, architecture-specific fast paths, fused operations, portability work, and optimization ideas that ordinary popularity rankings bury.',
+    emptyTitle: 'No kernel answered.',
+    emptyCopy: 'loosen a hardware filter or try another operation.',
+    footer: 'pressed by <a href="https://huggingface.co/juiceb0xc0de" target="_blank">juiceb0xc0de</a> · one repository per kernel result',
+    next: 'next pressing: build-graph filters',
+    catalog: 'kernel pressing',
+  },
+  docker: {
+    title: 'B-Sides — deep search for container recipes',
+    description: 'Search Docker and OCI build recipes on Hugging Face by meaning, base image, accelerator, CUDA or ROCm version, Python version, framework, service, and build facts.',
+    tagline: 'deep search · container recipes',
+    hero: 'The images nobody pushed.<br><em>Read the build.</em>',
+    placeholder: 'search by meaning… "Python 3.11 CUDA 12.8 PyTorch"',
+    promise: total => `<b id="hero-count">${total}</b> container artifacts · <b>recipes only</b> by default — flip <b>include archives</b> for the tarballs · search by <b>meaning</b>, <b>base image</b>, <b>accelerator</b>, or <b>build facts</b>`,
+    manifesto: 'The container crates hold the build instructions behind open ML: Dockerfiles, Compose stacks, and devcontainers that pin the exact CUDA, ROCm, Python, and framework versions a project actually ran on. It is the environment layer that model cards leave out.',
+    emptyTitle: 'No recipe answered.',
+    emptyCopy: 'loosen a build filter, or let the archives in.',
+    footer: 'pressed by <a href="https://huggingface.co/juiceb0xc0de" target="_blank">juiceb0xc0de</a> · one artifact per container result',
+    next: 'next pressing: layer-level build graphs',
+    catalog: 'container pressing',
+  },
+};
+
+/* pastel pairs: [top-band fill, pill fill] keyed by hash */
+const PASTELS = [
+  ['var(--rose)','var(--rose)'], ['var(--marigold)','var(--marigold)'],
+  ['var(--sage)','var(--sage)'], ['var(--powder)','var(--powder)'],
+  ['var(--lilac)','var(--lilac)'], ['var(--terra)','var(--terra)'],
+];
+const colorFor = s => PASTELS[[...s].reduce((a,c)=>a+c.charCodeAt(0),0) % PASTELS.length];
+const fmtN = n => n >= 1e9 ? (n/1e9).toFixed(1).replace(/\.0$/,'')+'B'
+              : n >= 1e6 ? (n/1e6).toFixed(1).replace(/\.0$/,'')+'M'
+              : n >= 1e3 ? (n/1e3).toFixed(1).replace(/\.0$/,'')+'K' : String(n);
+const esc = s => String(s).replace(/[&<>"']/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+const ROMAN = n => { // small roman numerals for card numbers
+  const map = [[1000,'M'],[900,'CM'],[500,'D'],[400,'CD'],[100,'C'],[90,'XC'],[50,'L'],[40,'XL'],[10,'X'],[9,'IX'],[5,'V'],[4,'IV'],[1,'I']];
+  let out = ''; n = (n % 3999) + 1;
+  for (const [v, r] of map) while (n >= v) { out += r; n -= v; }
+  return out;
+};
+
+function buildModelReq() {
+  const s = state.sel.models;
+  const pB = v => v ? Math.round(parseFloat(v) * 1e9) : null;
+  return {
+    query: $('q').value.trim(),
+    month_from: $('f-month-from').value || null,
+    month_to: $('f-month-to').value || null,
+    archs: [...s.archs], methods: [...s.methods], imports: [...s.imports],
+    relation: $('f-relation').value || null,
+    base_model: $('f-base').value.trim() || null,
+    license: $('f-license').value || null,
+    params_min: pB($('f-pmin').value), params_max: pB($('f-pmax').value),
+    context_min: $('f-ctx').value ? parseInt($('f-ctx').value) : null,
+    config_contains: $('f-config').value.trim() || null,
+    moe_only: s.moe, custom_code_only: s.custom,
+    exclude_families: [...state.sel.models.excludedFamilies],
+    exclude_quantizations: state.sel.models.excludeQuantizations,
+    sort: $('sort').value, page: state.page,
+  };
+}
+
+/* an inverted size range can never match anything — say so instead of asking
+   the backend for the empty set */
+function sizeRangeInvalid() {
+  const min = parseFloat($('f-pmin').value);
+  const max = parseFloat($('f-pmax').value);
+  const bad = Number.isFinite(min) && Number.isFinite(max) && min > max;
+  $('size-warn').style.display = bad ? '' : 'none';
+  return bad;
+}
+
+function buildDockerReq() {
+  const s = state.sel.docker;
+  const filters = {};
+  const put = (key, values) => { if (values.length) filters[key] = values; };
+  // Recipes are the product default; the archive toggle drops the constraint
+  // rather than widening it to a second kind.
+  if (!s.includeArchives) filters.artifact_kinds = ['recipe'];
+  put('repo_types', [...s.repo_types]);
+  for (const key of DOCKER_ARRAY_FILTERS) put(key, [...s[key]]);
+  for (const key of DOCKER_BOOL_FILTERS) if (s[key]) filters[key] = true;
+  return {
+    query: $('q').value.trim(), sort: $('sort').value,
+    page: state.page, filters,
+  };
+}
+
+function buildKernelReq() {
+  const s = state.sel.kernels;
+  const filters = {};
+  const put = (key, value) => {
+    if (value !== '' && value != null && (!Array.isArray(value) || value.length))
+      filters[key] = value;
+  };
+  put('month_from', $('k-month-from').value);
+  put('month_to', $('k-month-to').value);
+  put('author', $('k-author').value);
+  put('downloads_min', $('k-downloads-min').value ? parseInt($('k-downloads-min').value) : null);
+  put('downloads_max', $('k-downloads-max').value ? parseInt($('k-downloads-max').value) : null);
+  put('variant_count_min', $('k-variant-min').value ? parseInt($('k-variant-min').value) : null);
+  for (const key of ['languages','accelerators','cuda_archs','dtypes','intrinsics','torch_ops','torch_versions'])
+    put(key, [...s[key]]);
+  if (s.has_build_dir) filters.has_build_dir = true;
+  return {
+    query: $('q').value.trim(), sort: $('sort').value,
+    page: state.page, filters,
+  };
+}
+
+const REQ_BUILDERS = {models: buildModelReq, kernels: buildKernelReq, docker: buildDockerReq};
+const buildReq = () => REQ_BUILDERS[state.corpus]();
+
+// default exclusions are product defaults, not user intent — they leave the
+// landing state pristine, same as the default Docker recipe constraint.
+const modelIsPristine = r => !r.query && !r.month_from && !r.month_to && !r.archs.length
+  && !r.methods.length && !r.imports.length && !r.relation && !r.base_model
+  && !r.license && r.params_min == null && r.params_max == null
+  && r.context_min == null && !r.config_contains && !r.moe_only && !r.custom_code_only;
+const kernelIsPristine = r => !r.query && Object.keys(r.filters).length === 0;
+const dockerIsPristine = r => {
+  if (r.query) return false;
+  const keys = Object.keys(r.filters);
+  return keys.length === 0 || (keys.length === 1 && keys[0] === 'artifact_kinds');
+};
+const PRISTINE = {models: modelIsPristine, kernels: kernelIsPristine, docker: dockerIsPristine};
+const isPristine = r => PRISTINE[state.corpus](r);
+
+function tarotCard(m) {
+  const archTag = m.model_type || m.tags.find(t => state.facets.models._archset.has(t)) || '';
+  const [band] = colorFor(archTag || m.model_id);
+  const method = ['grpo','dpo','orpo','kto','ppo','sft','lora','merge'].find(t => m.tags.includes(t));
+
+  const pills = [];
+  for (const imp of (m.code_imports || []).filter(i => ['flash_attn','causal_conv1d','mamba_ssm','triton','fla'].includes(i)))
+    pills.push(`<span class="pill hot">${esc(imp)}</span>`);
+  if (m.gated) pills.push(`<span class="pill" style="--pc:var(--lilac)">gated</span>`);
+  if (m.tags.includes('unsloth')) pills.push(`<span class="pill" style="--pc:var(--sage)">unsloth</span>`);
+
+  const meta = [`<span>${esc(m.month || '')}</span>`];
+  if (m.params) meta.push(`<span>${fmtN(m.params)} params</span>`);
+  if (m.context_len) meta.push(`<span>${fmtN(m.context_len)} ctx</span>`);
+  meta.push(`<span>↓${fmtN(m.downloads||0)} ♥${fmtN(m.likes||0)}</span>`);
+  if (m.score != null) meta.push(`<span class="sc-match">${(m.score*100).toFixed(0)}%</span>`);
+
+  const lineage = m.base_model
+    ? `<div class="lineage">${esc(m.relation || 'b-side')} of ${esc(m.base_model)}</div>` : '';
+  const caption = [archTag, method].filter(Boolean).join(' · ') || 'text generation';
+
+  const [author, ...rest] = m.model_id.split('/');
+  return `<div class="tcard" style="--tc:${band}" data-href="https://huggingface.co/${encodeURIComponent(author)}/${rest.map(encodeURIComponent).join('/')}">
+    <div class="sky"><span class="num">№ ${ROMAN(m.row)}</span><span>${esc(m.month || '')}</span></div>
+    <div class="body">
+      <div class="mid">${esc(rest.join('/') || m.model_id)}</div>
+      <div class="author">${esc(author)}</div>
+      <div class="meta">${meta.join('')}</div>
+      ${pills.length ? `<div class="pills">${pills.join('')}</div>` : ''}
+      ${lineage}
+    </div>
+    <div class="caption">${esc(caption)}&nbsp;.</div>
+  </div>`;
+}
+
+function kernelCard(k) {
+  const selected = state.sel.kernels;
+  const [authorFromId, ...rest] = k.repo_id.split('/');
+  const author = k.author || authorFromId;
+  const name = rest.join('/') || k.repo_id;
+  const [band] = colorFor((k.accelerators || [])[0] || k.repo_id);
+  const preferSelected = (values, set, limit) => [...(values || [])]
+    .sort((a, b) => Number(set.has(b)) - Number(set.has(a))).slice(0, limit);
+
+  const pills = [];
+  for (const value of [...(k.languages || []), ...(k.accelerators || [])].slice(0, 4))
+    pills.push(`<span class="pill hot">${esc(value)}</span>`);
+  for (const value of (k.dtypes || []).slice(0, 2))
+    pills.push(`<span class="pill" style="--pc:var(--lilac)">${esc(value)}</span>`);
+  for (const value of preferSelected(k.intrinsics, selected.intrinsics, 2))
+    pills.push(`<span class="pill" style="--pc:var(--terra)">${esc(value)}</span>`);
+  for (const value of preferSelected(k.torch_ops, selected.torch_ops, 2))
+    pills.push(`<span class="pill" style="--pc:var(--sage)">${esc(value)}</span>`);
+
+  const meta = [`<span>${esc(k.month || '')}</span>`,
+    `<span>↓${fmtN(k.downloads||0)} ♥${fmtN(k.likes||0)}</span>`];
+  if (k.score != null) meta.push(`<span class="sc-match">${(k.score*100).toFixed(0)}%</span>`);
+  const variants = `${fmtN(k.variant_count || 0)} variant${k.variant_count === 1 ? '' : 's'}`;
+  const sources = `${fmtN(k.source_files || 0)} source file${k.source_files === 1 ? '' : 's'}`;
+  const href = `https://huggingface.co/${k.repo_id.split('/').map(encodeURIComponent).join('/')}`;
+
+  return `<div class="tcard kernel-card" style="--tc:${band}" data-href="${href}">
+    <div class="sky"><span class="num">№ ${ROMAN(k.row)}</span><span>${esc(k.month || '')}</span></div>
+    <div class="body">
+      <div class="mid">${esc(name)}</div>
+      <div class="author">${esc(author)}</div>
+      <div class="meta">${meta.join('')}</div>
+      ${pills.length ? `<div class="pills">${pills.slice(0, 10).join('')}</div>` : ''}
+      <div class="facts">${variants} · ${sources}</div>
+    </div>
+    <div class="caption">kernel repository&nbsp;.</div>
+  </div>`;
+}
+
+/* Buckets have no git revisions, and recipe rows carry the synthetic
+   `<recipe>` path rather than a real file — neither has a valid blob URL, so
+   those land on the repository page instead of a guaranteed 404. */
+function containerHref(c) {
+  const repoType = c.repo_type || 'model';
+  const path = c.artifact_path || '';
+  const repo = String(c.repo_id || '').split('/').map(encodeURIComponent).join('/');
+  if (repoType === 'bucket') return `https://huggingface.co/buckets/${repo}`;
+  const prefix = repoType === 'space' ? 'spaces/' : repoType === 'dataset' ? 'datasets/' : '';
+  const landing = `https://huggingface.co/${prefix}${repo}`;
+  if (!c.sha || !path || path === '<recipe>') return landing;
+  const file = path.split('/').map(encodeURIComponent).join('/');
+  return `${landing}/blob/${encodeURIComponent(c.sha)}/${file}`;
+}
+
+function dockerCard(c) {
+  const selected = state.sel.docker;
+  const [authorFromId, ...rest] = String(c.repo_id || '').split('/');
+  const author = c.author || authorFromId;
+  const name = rest.join('/') || c.repo_id || '';
+  const path = c.artifact_path || '';
+  const kind = c.artifact_kind || 'recipe';
+  const month = (c.created_at || '').slice(0, 7);
+  const [band] = colorFor((c.accelerators || [])[0] || (c.base_images || [])[0] || name);
+  const preferSelected = (values, set, limit) => [...(values || [])]
+    .sort((a, b) => Number(set.has(b)) - Number(set.has(a))).slice(0, limit);
+
+  const pills = [];
+  for (const value of (c.accelerators || []).slice(0, 2))
+    pills.push(`<span class="pill hot">${esc(value)}</span>`);
+  for (const value of preferSelected(c.cuda_versions, selected.cuda_versions, 2))
+    pills.push(`<span class="pill" style="--pc:var(--powder)">cuda ${esc(value)}</span>`);
+  for (const value of preferSelected(c.rocm_versions, selected.rocm_versions, 1))
+    pills.push(`<span class="pill" style="--pc:var(--terra)">rocm ${esc(value)}</span>`);
+  for (const value of preferSelected(c.python_versions, selected.python_versions, 2))
+    pills.push(`<span class="pill" style="--pc:var(--marigold)">py ${esc(value)}</span>`);
+  for (const value of preferSelected(c.frameworks, selected.frameworks, 3))
+    pills.push(`<span class="pill" style="--pc:var(--sage)">${esc(value)}</span>`);
+  if (c.has_compose) pills.push(`<span class="pill" style="--pc:var(--lilac)">compose</span>`);
+  if (c.has_devcontainer) pills.push(`<span class="pill" style="--pc:var(--lilac)">devcontainer</span>`);
+  if (c.has_multistage) pills.push(`<span class="pill" style="--pc:var(--lilac)">multi-stage</span>`);
+
+  const meta = [`<span>${esc(month)}</span>`,
+    `<span>↓${fmtN(c.downloads||0)} ♥${fmtN(c.likes||0)}</span>`];
+  if (c.score != null) meta.push(`<span class="sc-match">${(c.score*100).toFixed(0)}%</span>`);
+
+  const base = (c.base_images || [])[0];
+  const facts = [base ? `from ${esc(base)}` : '',
+    path && path !== '<recipe>' ? esc(path) : esc(kind)].filter(Boolean).join(' · ');
+  const caption = [kind, c.repo_type].filter(Boolean).join(' · ') || 'container artifact';
+
+  return `<div class="tcard docker-card" style="--tc:${band}" data-href="${esc(containerHref(c))}">
+    <div class="sky"><span class="num">№ ${ROMAN(c.row)}</span><span>${esc(month)}</span></div>
+    <div class="body">
+      <div class="mid">${esc(name)}</div>
+      <div class="author">${esc(author)}</div>
+      <div class="meta">${meta.join('')}</div>
+      ${pills.length ? `<div class="pills">${pills.slice(0, 10).join('')}</div>` : ''}
+      <div class="facts">${facts}</div>
+    </div>
+    <div class="caption">${esc(caption)}&nbsp;.</div>
+  </div>`;
+}
+
+function wireCards(scope) {
+  const fresh = [...scope.querySelectorAll('.tcard:not(.wired)')];
+  fresh.forEach(el => {
+    el.classList.add('wired');
+    el.addEventListener('click', () => window.open(el.dataset.href, '_blank'));
+  });
+  if (window.VanillaTilt) VanillaTilt.init(fresh, { max: 4, speed: 900, scale: 1.015, gyroscope: false });
+  if (window.gsap) gsap.from(fresh, { y: 16, opacity: 0, duration: .45, stagger: 0.04, ease: 'power3.out', clearProps: 'opacity,transform' });
+}
+
+// boot window: the backend returns 503 while the ~1.4 GB index streams in off
+// disk — retry politely instead of showing a broken page.
+async function getJSON(url, opts, tries = 60, delayMs = 1000) {
+  for (let i = 0; ; i++) {
+    const r = await fetch(url, opts);
+    if (r.ok) return r.json();
+    if (r.status !== 503 || i >= tries)
+      throw new Error((await r.json().catch(() => ({}))).detail
+                      || `request failed (${r.status})`);
+    await new Promise(res => setTimeout(res, delayMs));
+  }
+}
+
+async function loadSpread() {
+  try {
+    const d = await getJSON('/api/picks');
+    if (!d.picks.length) return;
+    $('spread-row').innerHTML = d.picks.map(p => `
+      <div class="pick">
+        ${tarotCard(p)}
+        <div class="note">“${esc(p.note)}”</div>
+        <div class="by">— ${esc(p.picked_by)}</div>
+      </div>`).join('');
+    wireCards($('spread-row'));
+    if (state.corpus === 'models') $('spread').style.display = '';
+  } catch (e) { /* picks are optional */ }
+}
+
+function idle() {
+  /* landing state: search engine at rest — spread only, no listing */
+  $('grid').innerHTML = '';
+  $('crates-head').style.display = 'none';
+  $('empty').style.display = 'none';
+  $('more').style.display = 'none';
+  $('spread').style.display = state.corpus === 'models' && $('spread-row').children.length ? '' : 'none';
+  const facets = state.facets[state.corpus];
+  $('status').innerHTML = facets
+    ? `<b>${facets.total.toLocaleString()}</b> ${IDLE_NOUNS[state.corpus]}` : '';
+}
+
+async function search(append=false) {
+  if (state.busy) return;
+  if (!state.ready[state.corpus]) {
+    $('status').textContent = WARMING[state.corpus];
+    return;
+  }
+  if (state.corpus === 'models' && sizeRangeInvalid()) return;
+  const reqCheck = buildReq();
+  if (isPristine(reqCheck)) { idle(); return; }
+  const corpus = state.corpus;
+  const epoch = state.epoch;
+  state.busy = true;
+  if (!append) { state.page = 0; $('grid').innerHTML = ''; }
+  $('results-wrap').parentElement.classList.add('loading');
+  $('empty').style.display = 'none';
+  try {
+    const req = buildReq();
+    const data = await getJSON(endpoint('search', corpus), { method: 'POST',
+      headers: {'Content-Type':'application/json'}, body: JSON.stringify(req) }, 60, 1000);
+    if (corpus !== state.corpus || epoch !== state.epoch) return;
+    state.total = data.total;
+    const rows = data[resultKey[corpus]] || [];
+    const html = rows.map(CARD_RENDERERS[corpus]).join('');
+    if (append) $('grid').insertAdjacentHTML('beforeend', html);
+    else $('grid').innerHTML = html;
+    wireCards($('grid'));
+
+    $('spread').style.display = 'none';
+    $('crates-head').style.display = '';
+    const noun = RESULT_NOUNS[corpus];
+    $('status').innerHTML = `<b>${data.total.toLocaleString()}</b> ${noun}` +
+      (req.query && req.sort === 'relevance' ? ` · matched by meaning to “${esc(req.query)}”` : ' match your filters');
+    $('empty').style.display = data.total === 0 ? 'block' : 'none';
+    $('more').style.display = $('grid').children.length < data.total ? 'block' : 'none';
+  } catch (e) {
+    if (corpus === state.corpus && epoch === state.epoch)
+      $('status').innerHTML = `⚠ ${esc(e.message)}`;
+  } finally {
+    if (corpus === state.corpus && epoch === state.epoch) {
+      $('results-wrap').parentElement.classList.remove('loading');
+      state.busy = false;
+    }
+  }
+}
+
+function chipbar(el, items, set, max=14) {
+  const render = (expanded) => {
+    const list = expanded ? items : items.slice(0, max);
+    el.innerHTML = list.map(i =>
+      `<span class="chip${set.has(i.v)?' on':''}" data-v="${esc(i.v)}">${esc(i.v)}<span class="n">${fmtN(i.n)}</span></span>`
+    ).join('') + (items.length > max
+      ? `<span class="chip more-toggle">${expanded ? '− less' : `+ ${items.length-max} more`}</span>` : '');
+    el.querySelectorAll('.chip').forEach(c => c.onclick = () => {
+      if (c.classList.contains('more-toggle')) return render(!expanded);
+      const v = c.dataset.v;
+      set.has(v) ? set.delete(v) : set.add(v);
+      c.classList.toggle('on');
+      search();
+    });
+  };
+  render(false);
+}
+
+function monthOptions(from, to, months) {
+  $(from).innerHTML = '<option value="">from the start</option>' +
+    months.map(m=>`<option>${m}</option>`).join('');
+  $(to).innerHTML = '<option value="">to the latest</option>' +
+    months.map(m=>`<option>${m}</option>`).join('');
+}
+
+function populateModelFacets(f) {
+  f._archset = new Set(f.archs.map(a => a.v));
+  monthOptions('f-month-from', 'f-month-to', f.months);
+  chipbar($('f-archs'), f.archs, state.sel.models.archs, 6);
+  chipbar($('f-methods'), f.methods, state.sel.models.methods, 6);
+  $('f-relation').innerHTML = '<option value="">any relation</option>' +
+    f.relations.map(r=>`<option value="${esc(r.v)}">${esc(r.v)} (${fmtN(r.n)})</option>`).join('');
+  $('f-license').innerHTML = '<option value="">any license</option>' +
+    f.licenses.map(l=>`<option value="${esc(l.v)}">${esc(l.v)} (${fmtN(l.n)})</option>`).join('');
+  if (f.enriched) {
+    if (f.imports.length) chipbar($('f-imports'), f.imports, state.sel.models.imports, 10);
+  } else {
+    $('deep-soon').style.display = '';
+    $('deep-filters').style.display = 'none';
+  }
+}
+
+function populateKernelFacets(f) {
+  monthOptions('k-month-from', 'k-month-to', f.months);
+  for (const [key, id, max] of [
+    ['languages','k-languages',10], ['accelerators','k-accelerators',8],
+    ['cuda_archs','k-cuda-archs',10], ['dtypes','k-dtypes',10],
+    ['intrinsics','k-intrinsics',10], ['torch_ops','k-torch-ops',10],
+    ['torch_versions','k-torch-versions',10],
+  ]) chipbar($(id), f[key] || [], state.sel.kernels[key], max);
+  $('k-author').innerHTML = '<option value="">any author</option>' +
+    (f.authors || []).map(a=>`<option value="${esc(a.v)}">${esc(a.v)} (${fmtN(a.n)})</option>`).join('');
+}
+
+/* checked means hidden. These are product defaults, so they render on; the
+   list is fixed by DEFAULT_EXCLUDED_FAMILIES and stays visible once unchecked. */
+function renderExclusions() {
+  const s = state.sel.models;
+  const rows = [['__quant', 'Quantizations', s.excludeQuantizations]].concat(
+    DEFAULT_EXCLUDED_FAMILIES.map(f => [f, FAMILY_LABELS[f] || f, s.excludedFamilies.has(f)]));
+  $('f-excludes').innerHTML = rows.map(([key, label, on]) =>
+    `<span class="ex-row${on ? ' on' : ''}" data-k="${esc(key)}"><span class="box"></span>${esc(label)}</span>`
+  ).join('');
+  $('f-excludes').querySelectorAll('.ex-row').forEach(row => row.onclick = () => {
+    const key = row.dataset.k;
+    if (key === '__quant') s.excludeQuantizations = !s.excludeQuantizations;
+    else s.excludedFamilies.has(key)
+      ? s.excludedFamilies.delete(key) : s.excludedFamilies.add(key);
+    row.classList.toggle('on');
+    search();
+  });
+}
+
+function populateDockerFacets(f) {
+  const s = state.sel.docker;
+  chipbar($('d-repo-types'), f.repo_types || [], s.repo_types, 6);
+  for (const [key, id, max] of [
+    ['accelerators','d-accelerators',8], ['cuda_versions','d-cuda-versions',10],
+    ['rocm_versions','d-rocm-versions',8], ['python_versions','d-python-versions',10],
+    ['frameworks','d-frameworks',10], ['base_images','d-base-images',10],
+    ['operating_systems','d-operating-systems',8],
+    ['package_managers','d-package-managers',8], ['services','d-services',10],
+    ['node_versions','d-node-versions',8],
+  ]) chipbar($(id), f[key] || [], s[key], max);
+}
+
+const FACET_POPULATORS = {
+  models: populateModelFacets, kernels: populateKernelFacets,
+  docker: populateDockerFacets,
+};
+
+function applyCopy() {
+  const copy = COPY[state.corpus];
+  const facets = state.facets[state.corpus];
+  const total = facets ? facets.total.toLocaleString() : '…';
+  document.title = copy.title;
+  document.querySelector('meta[name="description"]').content = copy.description;
+  $('tagline').textContent = copy.tagline;
+  $('hero-h').innerHTML = copy.hero;
+  $('q').placeholder = copy.placeholder;
+  $('promise').innerHTML = copy.promise(total);
+  $('manifesto').innerHTML = copy.manifesto;
+  $('empty-title').textContent = copy.emptyTitle;
+  $('empty-copy').textContent = copy.emptyCopy;
+  $('footer-main').innerHTML = copy.footer;
+  $('footer-next').textContent = copy.next;
+  $('catalog-copy').textContent = copy.catalog;
+  $('head-count').textContent = facets
+    ? `${total} ${HEAD_NOUNS[state.corpus]}` : '…';
+  $('crate-title').textContent = CRATE_TITLES[state.corpus];
+}
+
+async function loadFacets(corpus) {
+  if (state.ready[corpus]) return state.facets[corpus];
+  if (state.loading[corpus]) return state.loading[corpus];
+  state.loading[corpus] = getJSON(endpoint('facets', corpus)).then(f => {
+    state.facets[corpus] = f;
+    state.ready[corpus] = true;
+    FACET_POPULATORS[corpus](f);
+    return f;
+  }).finally(() => { state.loading[corpus] = null; });
+  return state.loading[corpus];
+}
+
+function resetResults() {
+  state.page = 0;
+  state.total = 0;
+  state.busy = false;
+  $('grid').innerHTML = '';
+  $('crates-head').style.display = 'none';
+  $('empty').style.display = 'none';
+  $('more').style.display = 'none';
+  $('results-wrap').parentElement.classList.remove('loading');
+}
+
+async function switchCorpus(corpus) {
+  state.corpus = corpus;
+  state.epoch++;
+  resetResults();
+  $('model-filters').style.display = corpus === 'models' ? '' : 'none';
+  $('kernel-filters').style.display = corpus === 'kernels' ? '' : 'none';
+  $('docker-filters').style.display = corpus === 'docker' ? '' : 'none';
+  $('spread').style.display = 'none';
+  applyCopy();
+  $('status').textContent = WARMING[corpus];
+  try {
+    await loadFacets(corpus);
+    if (state.corpus !== corpus) return;
+    applyCopy();
+    idle();
+  } catch (e) {
+    if (state.corpus === corpus)
+      $('status').innerHTML = `⚠ ${esc(e.message)}`;
+  }
+}
+
+function clearModels() {
+  for (const id of ['f-month-from','f-month-to','f-relation','f-license']) $(id).value = '';
+  for (const id of ['f-base','f-pmin','f-pmax','f-ctx','f-config']) $(id).value = '';
+  const s = state.sel.models;
+  s.archs.clear(); s.methods.clear(); s.imports.clear();
+  s.moe = s.custom = false;
+  $('f-moe').classList.remove('on'); $('f-custom').classList.remove('on');
+  $('model-filters').querySelectorAll('.chip.on').forEach(c => c.classList.remove('on'));
+  // clearing restores the product defaults; it does not switch them off, which
+  // would silently widen every search that follows.
+  s.excludedFamilies = new Set(DEFAULT_EXCLUDED_FAMILIES);
+  s.excludeQuantizations = true;
+  $('size-warn').style.display = 'none';
+  renderExclusions();
+}
+
+function clearKernels() {
+  for (const id of ['k-month-from','k-month-to','k-author']) $(id).value = '';
+  for (const id of ['k-downloads-min','k-downloads-max','k-variant-min']) $(id).value = '';
+  const s = state.sel.kernels;
+  for (const key of ['languages','accelerators','cuda_archs','dtypes','intrinsics','torch_ops','torch_versions'])
+    s[key].clear();
+  s.has_build_dir = false;
+  $('k-build').classList.remove('on');
+  $('kernel-filters').querySelectorAll('.chip.on').forEach(c => c.classList.remove('on'));
+}
+
+function clearDocker() {
+  const s = state.sel.docker;
+  s.repo_types.clear();
+  for (const key of DOCKER_ARRAY_FILTERS) s[key].clear();
+  for (const key of DOCKER_BOOL_FILTERS) s[key] = false;
+  s.includeArchives = false;   // back to recipes only
+  for (const id of ['d-compose','d-devcontainer','d-multistage','d-archives'])
+    $(id).classList.remove('on');
+  $('docker-filters').querySelectorAll('.chip.on').forEach(c => c.classList.remove('on'));
+}
+
+const CLEARERS = {models: clearModels, kernels: clearKernels, docker: clearDocker};
+
+async function init() {
+  applyCopy();
+  renderExclusions();
+  $('status').textContent = WARMING.models;
+  try {
+    await loadFacets('models');
+    applyCopy();
+    await loadSpread();
+    idle();
+  } catch (e) {
+    $('status').innerHTML = `⚠ ${esc(e.message)}`;
+  }
+}
+
+/* entrance: quiet, three beats */
+if (window.gsap) {
+  gsap.from('#hdr', { y: -14, opacity: 0, duration: .5, ease: 'power2.out' });
+  gsap.from('#hero-h', { y: 20, opacity: 0, duration: .6, delay: .1, ease: 'power3.out' });
+  gsap.from('#rule i', { scaleX: 0, duration: .4, stagger: .06, delay: .35, ease: 'power2.out' });
+  gsap.from('#term', { y: 14, opacity: 0, duration: .5, delay: .45, ease: 'power2.out' });
+}
+
+/* events */
+$('go').onclick = () => { if ($('q').value.trim()) $('sort').value = 'relevance'; search(); };
+$('q').addEventListener('keydown', e => { if (e.key === 'Enter') $('go').click(); });
+$('corpus').onchange = () => switchCorpus($('corpus').value);
+$('more').onclick = () => { state.page++; search(true); };
+$('sort').onchange = () => search();
+for (const id of ['f-month-from','f-month-to','f-relation','f-license'])
+  $(id).onchange = () => search();
+let deb;
+for (const id of ['f-base','f-pmin','f-pmax','f-ctx','f-config'])
+  $(id).addEventListener('input', () => { clearTimeout(deb); deb = setTimeout(() => search(), 450); });
+for (const [id, key] of [['f-moe','moe'],['f-custom','custom']])
+  $(id).onclick = () => { const s = state.sel.models; s[key] = !s[key]; $(id).classList.toggle('on'); search(); };
+for (const id of ['k-month-from','k-month-to','k-author'])
+  $(id).onchange = () => search();
+for (const id of ['k-downloads-min','k-downloads-max','k-variant-min'])
+  $(id).addEventListener('input', () => { clearTimeout(deb); deb = setTimeout(() => search(), 450); });
+$('k-build').onclick = () => {
+  const s = state.sel.kernels;
+  s.has_build_dir = !s.has_build_dir;
+  $('k-build').classList.toggle('on');
+  search();
+};
+for (const [id, key] of [['d-compose','has_compose'],['d-devcontainer','has_devcontainer'],
+                         ['d-multistage','has_multistage'],['d-archives','includeArchives']])
+  $(id).onclick = () => {
+    const s = state.sel.docker;
+    s[key] = !s[key];
+    $(id).classList.toggle('on');
+    search();
+  };
+$('clear').onclick = () => {
+  $('q').value = ''; $('sort').value = 'newest';
+  CLEARERS[state.corpus]();
+  search();
+};
+
+init();
+</script>
+</body>
+</html>

tests/test_config.py

@@ -0,0 +1,127 @@
+from pathlib import Path
+
+import pytest
+
+from bsides.config import Settings
+
+
+def test_defaults_match_the_production_crawl_contract() -> None:
+    settings = Settings.from_env(
+        {"HF_TOKEN": "present", "OPENAI_API_KEY": "present"}
+    )
+
+    assert settings.pipelines == (
+        "text-generation",
+        "text2text-generation",
+    )
+    assert settings.hub_requests_per_window == 2_400
+    assert settings.hub_window_seconds == 300.0
+    assert settings.embedding_model == "text-embedding-3-small"
+    assert settings.embedding_dimensions == 256
+    assert settings.embedding_tokens_per_minute == 4_500_000
+    assert settings.chunk_target_tokens == 1_200
+    assert settings.chunk_overlap_tokens == 150
+    assert settings.max_file_bytes == 2 * 1024 * 1024
+    assert settings.max_repo_bytes == 16 * 1024 * 1024
+    assert settings.checkpoint_every_repos == 2_500
+    assert settings.fetch_queue_multiplier == 4
+    assert settings.embed_workers == 8
+    assert settings.checkpoint_interval_seconds == 1_800.0
+    assert settings.progress_interval_seconds == 10.0
+    assert settings.tail_interval_seconds == 900.0
+    assert settings.tail_overlap_ids == 100
+    assert settings.dataset_repo_id == "juiceb0xc0de/b-sides-v2-index"
+    assert settings.run_id == "v2"
+    assert settings.lease_ttl_seconds == 1_800.0
+    assert settings.state_dir == Path("/tmp/bsides")
+    assert settings.mode == "both"
+
+
+def test_crawl_end_is_an_explicit_inclusive_upper_boundary() -> None:
+    settings = Settings.from_env(
+        {"BSIDES_CRAWL_END": "2026-08-30T06:00:00Z"}
+    )
+
+    assert settings.crawl_end == "2026-08-30T06:00:00Z"
+
+
+def test_environment_overrides_are_parsed_without_storing_secret_values() -> None:
+    settings = Settings.from_env(
+        {
+            "HF_TOKEN": "hf-secret",
+            "OPENAI_API_KEY": "openai-secret",
+            "BSIDES_MODE": "collect",
+            "BSIDES_HUB_REQUESTS_PER_5M": "1234",
+            "BSIDES_CHECKPOINT_EVERY_REPOS": "17",
+            "BSIDES_FETCH_QUEUE_MULTIPLIER": "3",
+            "BSIDES_EMBED_WORKERS": "5",
+            "BSIDES_EMBEDDING_TPM": "4000000",
+            "BSIDES_CHECKPOINT_INTERVAL_SECONDS": "45",
+            "BSIDES_PROGRESS_INTERVAL_SECONDS": "7",
+            "BSIDES_TAIL_INTERVAL_SECONDS": "60",
+            "BSIDES_STATE_DIR": "/tmp/custom-b-sides",
+            "BSIDES_DATASET": "owner/index",
+            "BSIDES_YEAR": "2025",
+            "BSIDES_CRAWL_END": "2026-08-30T06:00:00Z",
+        }
+    )
+
+    assert settings.mode == "collect"
+    assert settings.hub_requests_per_window == 1_234
+    assert settings.checkpoint_every_repos == 17
+    assert settings.fetch_queue_multiplier == 3
+    assert settings.embed_workers == 5
+    assert settings.embedding_tokens_per_minute == 4_000_000
+    assert settings.checkpoint_interval_seconds == 45.0
+    assert settings.progress_interval_seconds == 7.0
+    assert settings.tail_interval_seconds == 60.0
+    assert settings.state_dir == Path("/tmp/custom-b-sides")
+    assert settings.dataset_repo_id == "owner/index"
+    assert settings.crawl_year == 2025
+    assert settings.crawl_end == "2026-08-30T06:00:00Z"
+    assert settings.hf_token_present is True
+    assert settings.openai_api_key_present is True
+    assert "hf-secret" not in repr(settings)
+    assert "openai-secret" not in repr(settings)
+
+
+@pytest.mark.parametrize(
+    ("env", "message"),
+    [
+        ({"BSIDES_MODE": "wrong"}, "BSIDES_MODE"),
+        ({"BSIDES_HUB_REQUESTS_PER_5M": "0"}, "Hub request budget"),
+        ({"BSIDES_HUB_REQUESTS_PER_5M": "3000"}, "Hub request budget"),
+        ({"BSIDES_EMBEDDING_DIMENSIONS": "0"}, "embedding dimensions"),
+        ({"BSIDES_CHUNK_OVERLAP_TOKENS": "1200"}, "overlap"),
+        ({"BSIDES_FETCH_QUEUE_MULTIPLIER": "0"}, "queue multiplier"),
+        ({"BSIDES_EMBED_WORKERS": "0"}, "embedding workers"),
+        ({"BSIDES_EMBEDDING_TPM": "0"}, "embedding token rate"),
+        ({"BSIDES_CHECKPOINT_INTERVAL_SECONDS": "0"}, "checkpoint interval"),
+        ({"BSIDES_PROGRESS_INTERVAL_SECONDS": "0"}, "progress interval"),
+    ],
+)
+def test_invalid_settings_are_rejected(env: dict[str, str], message: str) -> None:
+    with pytest.raises(ValueError, match=message):
+        Settings.from_env(env)
+
+
+@pytest.mark.parametrize(
+    ("env", "missing"),
+    [
+        ({"OPENAI_API_KEY": "present"}, "HF_TOKEN"),
+        ({"HF_TOKEN": "present"}, "OPENAI_API_KEY"),
+    ],
+)
+def test_collection_validation_names_missing_credential(
+    env: dict[str, str], missing: str
+) -> None:
+    settings = Settings.from_env(env)
+
+    with pytest.raises(ValueError, match=missing):
+        settings.validate_for_collection()
+
+
+def test_search_mode_does_not_require_collection_credentials() -> None:
+    settings = Settings.from_env({"BSIDES_MODE": "search"})
+
+    settings.validate_for_collection()

tests/test_runtime.py

@@ -0,0 +1,874 @@
+from __future__ import annotations
+
+import os
+import pathlib
+import re
+import sqlite3
+import time
+from dataclasses import replace
+
+import numpy as np
+import pytest
+from fastapi.testclient import TestClient
+
+
+MODEL_DDL = """
+CREATE TABLE models (
+    row INTEGER PRIMARY KEY, model_id TEXT NOT NULL UNIQUE, author TEXT,
+    month TEXT, created_at TEXT, downloads INTEGER, likes INTEGER, tags TEXT,
+    base_model TEXT, relation TEXT, license TEXT, params INTEGER,
+    model_type TEXT, architectures TEXT, context_len INTEGER,
+    num_experts INTEGER, code_imports TEXT, gated INTEGER, config TEXT
+);
+"""
+
+KERNEL_DDL = """
+CREATE TABLE kernels (
+    row INTEGER PRIMARY KEY, repo_id TEXT NOT NULL UNIQUE, author TEXT,
+    created_at TEXT, month TEXT, last_modified TEXT, downloads INTEGER,
+    likes INTEGER, tags TEXT, languages TEXT, accelerators TEXT,
+    torch_versions TEXT, cuda_archs TEXT, cpu_archs TEXT,
+    operating_systems TEXT, dtypes TEXT, intrinsics TEXT, kernel_names TEXT,
+    torch_ops TEXT, build_variants TEXT, variant_count INTEGER,
+    has_build_dir INTEGER, source_files INTEGER, document TEXT
+);
+"""
+
+CONTAINER_DDL = """
+CREATE TABLE containers (
+ row INTEGER PRIMARY KEY, repo_id TEXT NOT NULL, repo_type TEXT NOT NULL,
+ artifact_path TEXT NOT NULL, artifact_kind TEXT NOT NULL,
+ author TEXT, sha TEXT NOT NULL, created_at TEXT, last_modified TEXT,
+ downloads INTEGER, likes INTEGER, tags TEXT, description TEXT,
+ artifact_files TEXT, qualification_reasons TEXT, base_images TEXT,
+ accelerators TEXT, cuda_versions TEXT, rocm_versions TEXT, python_versions TEXT,
+ node_versions TEXT, operating_systems TEXT, ports TEXT, services TEXT,
+ package_managers TEXT, frameworks TEXT, entrypoints TEXT, commands TEXT,
+ has_compose INTEGER, has_devcontainer INTEGER, has_multistage INTEGER,
+ source_files INTEGER, source_bytes INTEGER, document TEXT, document_hash TEXT
+);
+"""
+
+FIXTURE_MODELS = [
+    (0, "indie/alpha", "indie", "2024-01", "2024-01-10T00:00:00Z", 10, 1,
+     '["llama","sft"]', None, "finetune", "mit", None, "llama", None, None,
+     None, None, 0),
+    (1, "indie/beta", "lab", "2025-02", "2025-02-02T00:00:00Z", 500, 9,
+     '["mamba"]', None, None, "apache-2.0", None, "mamba", None, None, None,
+     None, 0),
+]
+
+FIXTURE_KERNELS = [
+    (0, "alice/fused-gemm", "alice", "2025-01-10T00:00:00Z", "2025-01",
+     "2025-01-11T00:00:00Z", 100, 3, '["kernels"]', '["cuda","python"]',
+     '["nvidia"]', '["2.5"]', '["sm_90"]', '[]', '["linux"]',
+     '["bf16"]', '["mma_sync"]', '["fused_gemm"]', '["matmul"]',
+     '["torch25-cu124"]', 3, 1, 4, "fused gemm kernel"),
+    (1, "bob/paged-attention", "bob", "2024-06-02T00:00:00Z", "2024-06",
+     "2024-06-03T00:00:00Z", 20, 8, '["kernels"]', '["triton","python"]',
+     '["nvidia"]', '["2.4"]', '["sm_80"]', '[]', '["linux"]',
+     '["fp32"]', '["tl.dot"]', '["paged_attention"]', '["attention"]',
+     '[]', 1, 0, 2, "paged attention kernel"),
+]
+
+FIXTURE_CONTAINERS = [
+    (0, "alice/cuda-recipe", "model", "Dockerfile", "recipe", "alice",
+     "sha-cuda", "2025-02-01T00:00:00Z", "2025-02-02T00:00:00Z", 300, 9,
+     '["docker","cuda"]', "CUDA PyTorch recipe", '["Dockerfile"]',
+     '["dockerfile","dependencies"]',
+     '["nvidia/cuda:12.8.0-runtime-ubuntu22.04"]', '["nvidia"]', '["12.8"]',
+     '[]', '["3.11"]', '[]', '["ubuntu22.04"]', '["7860"]', '["api"]',
+     '["pip"]', '["pytorch"]', '["python app.py"]', '["uvicorn app:app"]',
+     0, 0, 1, 6, 4096, "python 3.11 cuda 12.8 pytorch recipe", "hash-cuda"),
+    (1, "bob/rocm-recipe", "space", "docker/Dockerfile", "recipe", "bob",
+     "sha-rocm", "2025-03-01T00:00:00Z", "2025-03-02T00:00:00Z", 120, 4,
+     '["docker","rocm"]', "ROCm build", '["docker/Dockerfile"]',
+     '["dockerfile"]', '["rocm/pytorch:latest"]', '["amd"]', '[]', '["6.1"]',
+     '["3.12"]', '["20"]', '["ubuntu24.04"]', '["7860"]', '[]',
+     '["apt","pip"]', '["pytorch"]', '[]', '["python launch.py"]',
+     0, 0, 0, 5, 3072, "python 3.12 rocm pytorch recipe", "hash-rocm"),
+    (2, "carol/compose-stack", "dataset", "compose/Dockerfile", "recipe",
+     "carol", "sha-compose", "2025-04-01T00:00:00Z",
+     "2025-04-02T00:00:00Z", 80, 6, '["docker","compose"]',
+     "Compose-backed stack",
+     '["compose/Dockerfile","compose/docker-compose.yml"]',
+     '["compose","devcontainer"]', '["python:3.10-slim"]', '[]', '[]', '[]',
+     '["3.10"]', '["18"]', '["debian"]', '["5432","8888"]',
+     '["jupyter","postgres"]', '["apt","pip"]', '["fastapi"]',
+     '["./boot.sh"]', '["docker compose up"]', 1, 1, 0, 8, 8192,
+     "compose jupyter postgres fastapi stack", "hash-compose"),
+    (3, "dana/archive-bundle", "dataset", "artifacts/container.tar.gz",
+     "archive", "dana", "sha-archive", "2025-05-01T00:00:00Z",
+     "2025-05-02T00:00:00Z", 40, 1, '["docker","archive"]',
+     "Archived CUDA image", '["artifacts/container.tar.gz"]', '["archive"]',
+     '["ubuntu:22.04"]', '["nvidia"]', '["12.8"]', '[]', '["3.11"]', '[]',
+     '["ubuntu22.04"]', '["8080"]', '["worker"]', '["pip"]',
+     '["pytorch"]', '["./serve.sh"]', '["python worker.py"]',
+     0, 0, 0, 2, 2048, "python 3.11 cuda 12.8 archive image",
+     "hash-archive"),
+]
+
+
+def write_kernel_index(path, rows=FIXTURE_KERNELS, dimensions=4):
+    path.mkdir(parents=True, exist_ok=True)
+    connection = sqlite3.connect(path / "meta.sqlite")
+    connection.executescript(KERNEL_DDL)
+    connection.executemany(
+        f"INSERT INTO kernels VALUES ({','.join('?' * 24)})", rows)
+    connection.commit()
+    connection.close()
+    matrix = np.zeros((len(rows), dimensions), dtype=np.float16)
+    for row in range(len(rows)):
+        matrix[row, row % dimensions] = 1.0
+    np.save(path / "embeddings.f16.npy", matrix)
+
+
+def write_container_index(path, rows=FIXTURE_CONTAINERS, dimensions=4):
+    path.mkdir(parents=True, exist_ok=True)
+    connection = sqlite3.connect(path / "meta.sqlite")
+    connection.executescript(CONTAINER_DDL)
+    connection.executemany(
+        f"INSERT INTO containers VALUES ({','.join('?' * 35)})", rows)
+    connection.commit()
+    connection.close()
+    matrix = np.zeros((len(rows), dimensions), dtype=np.float16)
+    for row in range(len(rows)):
+        matrix[row, row % dimensions] = 1.0
+    np.save(path / "embeddings.f16.npy", matrix)
+
+
+@pytest.fixture
+def http_client(tmp_path):
+    """The real app over a real two-row index, swapped in by registry key.
+
+    TestClient is built without its context manager on purpose: entering the
+    lifespan would start the collector thread, which this test is not about.
+    """
+    import app as app_module
+
+    from bsides.search_indexes import ModelAdapter
+
+    conn = sqlite3.connect(tmp_path / "meta.sqlite")
+    conn.executescript(MODEL_DDL)
+    conn.executemany(
+        f"INSERT INTO models VALUES ({','.join('?' * 19)})",
+        [row + (None,) for row in FIXTURE_MODELS])
+    conn.commit()
+    conn.close()
+    matrix = np.zeros((2, 4), dtype=np.float16)
+    matrix[0, 0] = matrix[1, 1] = 1.0
+    np.save(tmp_path / "embeddings.f16.npy", matrix)
+
+    original = app_module.registry.index("models")
+    spec = replace(app_module.MODEL_SPEC, local_dir=tmp_path, dimensions=4)
+    index = app_module.registry.register(ModelAdapter(spec))
+    index.load()
+    assert index.ready.is_set(), index.error
+    try:
+        yield TestClient(app_module.app)
+    finally:
+        app_module.registry.register(original.adapter)
+
+
+@pytest.fixture
+def kernel_http_client(http_client, tmp_path):
+    import app as app_module
+
+    from bsides.search_indexes import KernelAdapter
+
+    kernel_dir = tmp_path / "kernels"
+    write_kernel_index(kernel_dir)
+    original = app_module.registry.index("kernels")
+    spec = replace(app_module.KERNEL_SPEC, local_dir=kernel_dir, dimensions=4)
+    index = app_module.registry.register(KernelAdapter(spec))
+    index.load()
+    assert index.ready.is_set(), index.error
+    try:
+        yield http_client
+    finally:
+        app_module.registry.register(original.adapter)
+
+
+@pytest.fixture
+def docker_http_client(http_client, tmp_path):
+    import app as app_module
+
+    from bsides.search_indexes import ContainerAdapter
+
+    docker_dir = tmp_path / "docker"
+    write_container_index(docker_dir)
+    original = app_module.registry.index("docker")
+    spec = replace(app_module.DOCKER_SPEC, local_dir=docker_dir, dimensions=4)
+    index = app_module.registry.register(ContainerAdapter(spec))
+    index.load()
+    assert index.ready.is_set(), index.error
+    try:
+        yield http_client
+    finally:
+        app_module.registry.register(original.adapter)
+
+
+@pytest.fixture
+def all_corpora_http_client(kernel_http_client, tmp_path):
+    import app as app_module
+
+    from bsides.search_indexes import ContainerAdapter
+
+    docker_dir = tmp_path / "docker"
+    write_container_index(docker_dir)
+    original = app_module.registry.index("docker")
+    spec = replace(app_module.DOCKER_SPEC, local_dir=docker_dir, dimensions=4)
+    index = app_module.registry.register(ContainerAdapter(spec))
+    index.load()
+    assert index.ready.is_set(), index.error
+    try:
+        yield kernel_http_client
+    finally:
+        app_module.registry.register(original.adapter)
+
+
+def test_app_registers_kernel_corpus_configuration() -> None:
+    import app as app_module
+
+    spec = app_module.registry.index("kernels").spec
+
+    assert spec is app_module.KERNEL_SPEC
+    assert spec.key == "kernels"
+    assert spec.dataset_id == os.environ.get(
+        "BSIDES_KERNEL_DATASET", "juiceb0xc0de/b-sides-v2-kernels")
+    assert spec.local_dir == app_module.INDEX_DIR / "kernels"
+    assert spec.table == "kernels"
+    assert spec.id_column == "repo_id"
+    assert spec.embed_model == "text-embedding-3-small"
+    assert spec.dimensions == 256
+
+
+def test_app_registers_docker_corpus_configuration() -> None:
+    import app as app_module
+
+    spec = app_module.registry.index("docker").spec
+
+    assert spec is app_module.DOCKER_SPEC
+    assert spec.key == "docker"
+    assert spec.dataset_id == os.environ.get(
+        "BSIDES_CONTAINER_DATASET", "juiceb0xc0de/b-sides-v2-containers")
+    assert spec.local_dir == app_module.INDEX_DIR / "docker"
+    assert spec.table == "containers"
+    assert spec.id_column == "repo_id"
+    assert spec.embed_model == "text-embedding-3-small"
+    assert spec.dimensions == 256
+
+
+def test_kernel_facets_and_search_use_kernel_response_shape(
+        kernel_http_client) -> None:
+    facets = kernel_http_client.get("/api/facets?corpus=kernels")
+    search = kernel_http_client.post(
+        "/api/search?corpus=kernels",
+        json={"sort": "downloads", "filters": {
+            "languages": ["cuda", "triton"],
+            "has_build_dir": True,
+            "variant_count_min": 2,
+        }},
+    )
+
+    assert facets.status_code == 200
+    assert facets.json()["total"] == 2
+    assert {item["v"]: item["n"]
+            for item in facets.json()["languages"]} == {
+                "python": 2, "cuda": 1, "triton": 1}
+    assert search.status_code == 200
+    assert set(search.json()) == {"total", "kernels"}
+    assert search.json()["total"] == 1
+    assert [item["repo_id"] for item in search.json()["kernels"]] == [
+        "alice/fused-gemm"]
+    assert search.json()["kernels"][0]["languages"] == ["cuda", "python"]
+
+
+def test_docker_facets_and_search_use_container_response_shape(
+        docker_http_client) -> None:
+    facets = docker_http_client.get("/api/facets?corpus=docker")
+    search = docker_http_client.post(
+        "/api/search?corpus=docker",
+        json={"sort": "downloads", "filters": {
+            "artifact_kinds": ["recipe"],
+            "python_versions": ["3.11"],
+            "cuda_versions": ["12.8"],
+            "frameworks": ["pytorch"],
+        }},
+    )
+
+    assert facets.status_code == 200
+    assert facets.json()["total"] == 4
+    assert {item["v"]: item["n"]
+            for item in facets.json()["artifact_kinds"]} == {
+                "recipe": 3, "archive": 1}
+    assert search.status_code == 200
+    assert set(search.json()) == {"total", "containers"}
+    assert search.json()["total"] == 1
+    assert [item["repo_id"] for item in search.json()["containers"]] == [
+        "alice/cuda-recipe"]
+    assert search.json()["containers"][0]["base_images"] == [
+        "nvidia/cuda:12.8.0-runtime-ubuntu22.04"]
+
+
+def test_failed_kernel_load_does_not_affect_model_search(
+        http_client, tmp_path) -> None:
+    import app as app_module
+
+    from bsides.search_indexes import KernelAdapter
+
+    bad_dir = tmp_path / "bad-kernels"
+    write_kernel_index(bad_dir, rows=FIXTURE_KERNELS[:1], dimensions=8)
+    original = app_module.registry.index("kernels")
+    spec = replace(app_module.KERNEL_SPEC, local_dir=bad_dir, dimensions=4)
+    failed = app_module.registry.register(KernelAdapter(spec))
+    failed.load()
+    try:
+        kernel_response = http_client.get("/api/facets?corpus=kernels")
+        model_response = http_client.post(
+            "/api/search", json={"sort": "downloads"})
+
+        assert failed.error and "dimensions" in failed.error
+        assert kernel_response.status_code == 503
+        assert model_response.status_code == 200
+        assert model_response.json()["total"] == 2
+        assert set(model_response.json()) == {"total", "models"}
+    finally:
+        app_module.registry.register(original.adapter)
+
+
+def test_failed_docker_load_does_not_affect_model_search(
+        http_client, tmp_path) -> None:
+    import app as app_module
+
+    from bsides.search_indexes import ContainerAdapter
+
+    bad_dir = tmp_path / "bad-docker"
+    write_container_index(bad_dir, rows=FIXTURE_CONTAINERS[:1], dimensions=8)
+    original = app_module.registry.index("docker")
+    spec = replace(app_module.DOCKER_SPEC, local_dir=bad_dir, dimensions=4)
+    failed = app_module.registry.register(ContainerAdapter(spec))
+    failed.load()
+    try:
+        docker_response = http_client.get("/api/facets?corpus=docker")
+        model_response = http_client.post(
+            "/api/search", json={"sort": "downloads"})
+
+        assert failed.error and "dimensions" in failed.error
+        assert docker_response.status_code == 503
+        assert model_response.status_code == 200
+        assert model_response.json()["total"] == 2
+        assert set(model_response.json()) == {"total", "models"}
+    finally:
+        app_module.registry.register(original.adapter)
+
+
+def test_reload_endpoint_hot_swaps_only_the_kernel_corpus(
+        kernel_http_client, monkeypatch) -> None:
+    import app as app_module
+
+    index = app_module.registry.index("kernels")
+    target = index.spec.local_dir
+    replacement = [(0, *FIXTURE_KERNELS[1][1:])]
+
+    def downloader(dataset_id, **kwargs):
+        assert dataset_id == index.spec.dataset_id
+        assert kwargs["local_dir"] == target
+        (target / "meta.sqlite").unlink(missing_ok=True)
+        (target / "embeddings.f16.npy").unlink(missing_ok=True)
+        write_kernel_index(target, rows=replacement, dimensions=4)
+
+    monkeypatch.setattr(app_module, "RELOAD_TOKEN", "correct-horse")
+    monkeypatch.setattr(app_module.registry, "downloader", downloader)
+
+    response = kernel_http_client.post(
+        "/api/reload?corpus=kernels", json={"token": "correct-horse"})
+
+    assert response.status_code == 200
+    assert response.json() == {
+        "status": "reload started", "corpus": "kernels"}
+    assert _await_rows(index, 1), index.error
+    kernel_body = kernel_http_client.post(
+        "/api/search?corpus=kernels", json={"sort": "downloads"}).json()
+    model_body = kernel_http_client.post(
+        "/api/search", json={"sort": "downloads"}).json()
+    assert [item["repo_id"] for item in kernel_body["kernels"]] == [
+        "bob/paged-attention"]
+    assert model_body["total"] == 2
+    assert set(model_body) == {"total", "models"}
+
+
+def test_reload_endpoint_hot_swaps_only_the_docker_corpus(
+        docker_http_client, monkeypatch) -> None:
+    import app as app_module
+
+    index = app_module.registry.index("docker")
+    target = index.spec.local_dir
+    replacement = [(0, *FIXTURE_CONTAINERS[1][1:])]
+
+    def downloader(dataset_id, **kwargs):
+        assert dataset_id == index.spec.dataset_id
+        assert kwargs["local_dir"] == target
+        (target / "meta.sqlite").unlink(missing_ok=True)
+        (target / "embeddings.f16.npy").unlink(missing_ok=True)
+        write_container_index(target, rows=replacement, dimensions=4)
+
+    monkeypatch.setattr(app_module, "RELOAD_TOKEN", "correct-horse")
+    monkeypatch.setattr(app_module.registry, "downloader", downloader)
+
+    response = docker_http_client.post(
+        "/api/reload?corpus=docker", json={"token": "correct-horse"})
+
+    assert response.status_code == 200
+    assert response.json() == {
+        "status": "reload started", "corpus": "docker"}
+    assert _await_rows(index, 1), index.error
+    docker_body = docker_http_client.post(
+        "/api/search?corpus=docker", json={"sort": "downloads"}).json()
+    model_body = docker_http_client.post(
+        "/api/search", json={"sort": "downloads"}).json()
+    assert [item["repo_id"] for item in docker_body["containers"]] == [
+        "bob/rocm-recipe"]
+    assert model_body["total"] == 2
+    assert set(model_body) == {"total", "models"}
+
+
+def test_search_response_keeps_the_total_models_envelope(http_client) -> None:
+    response = http_client.post("/api/search", json={"sort": "downloads"})
+
+    assert response.status_code == 200
+    body = response.json()
+    assert set(body) == {"total", "models"}
+    assert body["total"] == 2
+    assert [m["model_id"] for m in body["models"]] == [
+        "indie/beta", "indie/alpha"]
+    assert body["models"][0]["tags"] == ["mamba"]  # JSON columns decoded
+
+
+def test_model_search_exclusions_are_explicit_and_api_compatible(
+        http_client) -> None:
+    default = http_client.post(
+        "/api/search", json={"sort": "downloads"}).json()
+    excluded = http_client.post(
+        "/api/search",
+        json={"sort": "downloads", "exclude_families": ["llama"]},
+    )
+
+    assert excluded.status_code == 200
+    assert set(excluded.json()) == {"total", "models"}
+    assert {m["model_id"] for m in default["models"]} == {
+        "indie/alpha", "indie/beta"}
+    assert [m["model_id"] for m in excluded.json()["models"]] == [
+        "indie/beta"]
+
+
+def test_search_defaults_to_the_models_corpus(http_client) -> None:
+    default = http_client.post("/api/search", json={"sort": "downloads"})
+    explicit = http_client.post(
+        "/api/search?corpus=models", json={"sort": "downloads"})
+
+    assert default.json() == explicit.json()
+
+
+class RecordingClient:
+    """Embedding client double that records the app's outbound request."""
+
+    def __init__(self) -> None:
+        self.calls: list[dict] = []
+        self.embeddings = self
+
+    def create(self, **kwargs):
+        self.calls.append(kwargs)
+        return type("Response", (), {
+            "data": [type("Item", (), {"embedding": [1.0, 0.0, 0.0, 0.0]})()]
+        })()
+
+
+def test_semantic_searches_use_their_assigned_corpus_clients(
+        all_corpora_http_client, monkeypatch) -> None:
+    import app as app_module
+
+    model = RecordingClient()
+    kernel = RecordingClient()
+    docker = RecordingClient()
+    monkeypatch.setattr(app_module, "query_clients", {
+        "models": model, "kernels": kernel, "docker": docker,
+    })
+
+    model_response = all_corpora_http_client.post(
+        "/api/search", json={"query": "mamba hybrid architecture"})
+    kernel_response = all_corpora_http_client.post(
+        "/api/search?corpus=kernels", json={"query": "fused attention"})
+    docker_response = all_corpora_http_client.post(
+        "/api/search?corpus=docker", json={"query": "python 3.11 cuda 12.8"})
+
+    assert model_response.status_code == 200
+    assert kernel_response.status_code == 200
+    assert docker_response.status_code == 200
+    assert model.calls == [{
+        "model": "text-embedding-3-small",
+        "dimensions": 4,
+        "input": "mamba hybrid architecture",
+    }]
+    assert kernel.calls == [{
+        "model": "text-embedding-3-small",
+        "dimensions": 4,
+        "input": "fused attention",
+    }]
+    assert docker.calls == [{
+        "model": "text-embedding-3-small",
+        "dimensions": 4,
+        "input": "python 3.11 cuda 12.8",
+    }]
+
+
+def test_models_client_remains_the_oai_compatibility_shim() -> None:
+    import app as app_module
+
+    assert set(app_module.query_clients) == {"models", "kernels", "docker"}
+    assert app_module.oai is app_module.query_clients["models"]
+
+
+def test_semantic_search_without_a_key_is_unavailable_not_a_crash(
+        http_client, monkeypatch) -> None:
+    import app as app_module
+
+    monkeypatch.setitem(app_module.query_clients, "models", None)
+    response = http_client.post(
+        "/api/search", json={"query": "mamba hybrid architecture"})
+
+    assert response.status_code == 503
+    assert "OPENAI_API_KEY" in response.json()["detail"]
+
+
+def test_docker_semantic_search_without_a_key_is_unavailable_not_a_crash(
+        docker_http_client, monkeypatch) -> None:
+    import app as app_module
+
+    monkeypatch.setitem(app_module.query_clients, "docker", None)
+    response = docker_http_client.post(
+        "/api/search?corpus=docker", json={"query": "python 3.11 cuda 12.8"})
+    model_response = docker_http_client.post(
+        "/api/search", json={"sort": "downloads"})
+
+    assert response.status_code == 503
+    assert "OPENAI_DOCKER_API_KEY" in response.json()["detail"]
+    assert model_response.status_code == 200
+
+
+def test_facets_and_picks_still_answer(http_client) -> None:
+    facets = http_client.get("/api/facets")
+    assert facets.status_code == 200
+    assert facets.json()["total"] == 2
+    assert {a["v"] for a in facets.json()["archs"]} == {"llama", "mamba"}
+
+    picks = http_client.get("/api/picks")
+    assert picks.status_code == 200
+    assert "picks" in picks.json()
+
+
+def test_unknown_corpus_is_a_404(http_client) -> None:
+    assert http_client.get("/api/facets?corpus=bogus").status_code == 404
+
+
+# ── reload: the publish_loop.py wire contract ─────────────────────────────────
+# publish_loop.reload_space POSTs {"token": ...} and reads 200 / 403 / 503.
+
+def _await_rows(index, expected, timeout=10.0):
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if index.rows == expected and index.ready.is_set():
+            return True
+        time.sleep(0.01)
+    return False
+
+
+def test_reload_without_a_configured_token_is_503(http_client, monkeypatch):
+    import app as app_module
+
+    monkeypatch.setattr(app_module, "RELOAD_TOKEN", "")
+    response = http_client.post("/api/reload", json={"token": "anything"})
+
+    assert response.status_code == 503
+    assert "BSIDES_RELOAD_TOKEN" in response.json()["detail"]
+
+
+def test_reload_with_a_wrong_token_is_403(http_client, monkeypatch):
+    import app as app_module
+
+    monkeypatch.setattr(app_module, "RELOAD_TOKEN", "correct-horse")
+    index = app_module.registry.index("models")
+
+    response = http_client.post("/api/reload", json={"token": "guess"})
+
+    assert response.status_code == 403
+    assert index.rows == 2  # untouched
+
+
+def test_reload_with_an_empty_body_is_rejected(http_client, monkeypatch):
+    import app as app_module
+
+    monkeypatch.setattr(app_module, "RELOAD_TOKEN", "correct-horse")
+    assert http_client.post("/api/reload", json={}).status_code == 403
+
+
+def test_reload_with_the_right_token_swaps_the_index(http_client, monkeypatch):
+    import app as app_module
+
+    index = app_module.registry.index("models")
+    target = index.spec.local_dir
+
+    def downloader(dataset_id, **kwargs):
+        (target / "meta.sqlite").unlink(missing_ok=True)
+        (target / "embeddings.f16.npy").unlink(missing_ok=True)
+        conn = sqlite3.connect(target / "meta.sqlite")
+        conn.executescript(MODEL_DDL)
+        conn.executemany(
+            f"INSERT INTO models VALUES ({','.join('?' * 19)})",
+            [FIXTURE_MODELS[0] + (None,)])
+        conn.commit()
+        conn.close()
+        np.save(target / "embeddings.f16.npy",
+                np.array([[1, 0, 0, 0]], dtype=np.float16))
+
+    monkeypatch.setattr(app_module, "RELOAD_TOKEN", "correct-horse")
+    monkeypatch.setattr(app_module.registry, "downloader", downloader)
+
+    response = http_client.post("/api/reload", json={"token": "correct-horse"})
+
+    assert response.status_code == 200
+    assert response.json()["status"] == "reload started"
+    assert _await_rows(index, 1), index.error
+    assert index.error is None
+    # the swap is visible over HTTP, not just in memory
+    body = http_client.post("/api/search", json={"sort": "downloads"}).json()
+    assert body["total"] == 1
+    assert [m["model_id"] for m in body["models"]] == ["indie/alpha"]
+
+
+def test_reload_of_an_unknown_corpus_is_a_404(http_client, monkeypatch):
+    import app as app_module
+
+    monkeypatch.setattr(app_module, "RELOAD_TOKEN", "correct-horse")
+    response = http_client.post(
+        "/api/reload?corpus=bogus", json={"token": "correct-horse"})
+
+    assert response.status_code == 404
+    assert not app_module._reload_lock.locked()  # gate ran before the lock
+
+
+def test_endpoints_503_until_the_index_is_ready(tmp_path) -> None:
+    import app as app_module
+
+    from bsides.search_indexes import ModelAdapter
+
+    original = app_module.registry.index("models")
+    spec = replace(app_module.MODEL_SPEC, local_dir=tmp_path)
+    app_module.registry.register(ModelAdapter(spec))  # registered, never loaded
+    try:
+        client = TestClient(app_module.app)
+        assert client.post("/api/search", json={}).status_code == 503
+        assert client.get("/api/facets").status_code == 503
+    finally:
+        app_module.registry.register(original.adapter)
+
+
+def test_search_index_download_excludes_crawler_staging() -> None:
+    # The index dataset also carries the multi-GB crawler checkpoints under
+    # staging/. The models spec must allow-list only the two index files, so a
+    # boot download can never drag the staging tree onto the Space.
+    import app as app_module
+
+    from bsides.search_indexes import download_index
+
+    calls: list[tuple[str, dict]] = []
+
+    def downloader(dataset_id: str, **kwargs) -> None:
+        calls.append((dataset_id, kwargs))
+
+    spec = app_module.MODEL_SPEC
+    download_index(downloader, spec)
+
+    assert calls == [
+        (
+            spec.dataset_id,
+            {
+                "repo_type": "dataset",
+                "local_dir": spec.local_dir,
+                "allow_patterns": ["embeddings.f16.npy", "meta.sqlite"],
+            },
+        )
+    ]
+
+
+def test_docker_index_download_allows_only_published_search_files() -> None:
+    import app as app_module
+
+    from bsides.search_indexes import download_index
+
+    calls: list[tuple[str, dict]] = []
+
+    def downloader(dataset_id: str, **kwargs) -> None:
+        calls.append((dataset_id, kwargs))
+
+    spec = app_module.DOCKER_SPEC
+    download_index(downloader, spec)
+
+    assert calls == [
+        (
+            spec.dataset_id,
+            {
+                "repo_type": "dataset",
+                "local_dir": spec.local_dir,
+                "allow_patterns": ["embeddings.f16.npy", "meta.sqlite"],
+            },
+        )
+    ]
+
+
+def test_search_query_uses_the_loaded_index_dimensions(tmp_path) -> None:
+    # Dimensions sent to the embedding API come off the loaded matrix, not the
+    # spec, so a corpus published at a different width still queries correctly.
+    from bsides.search_indexes import LoadedIndex, embed_query
+
+    import app as app_module
+
+    calls: list[dict] = []
+
+    class Embeddings:
+        def create(self, **kwargs):
+            calls.append(kwargs)
+            item = type("Item", (), {"embedding": [1.0] + [0.0] * 255})()
+            return type("Response", (), {"data": [item]})()
+
+    index = LoadedIndex(replace(app_module.MODEL_SPEC, local_dir=tmp_path))
+    index.matrix = np.zeros((1, 256), dtype=np.float32)
+    client = type("Client", (), {"embeddings": Embeddings()})()
+
+    vector = embed_query(index, client, "odd attention")
+
+    assert vector.shape == (256,)
+    assert calls == [{
+        "model": "text-embedding-3-small",
+        "dimensions": 256,
+        "input": "odd attention",
+    }]
+
+
+# ── three-corpus frontend contract ───────────────────────────────────────────
+# The UI is one hand-written file with no JavaScript test runner, so these read
+# the source and pin the product decisions that regress silently: the corpus
+# list, per-corpus state, the visible default exclusions, and the generic URL
+# builder that a models-vs-kernels ternary would quietly break.
+
+DEFAULT_EXCLUDED_FAMILIES = (
+    'llama', 'qwen', 'gemma', 'mistral', 'deepseek', 'phi', 'granite')
+
+
+def _page() -> str:
+    path = pathlib.Path(__file__).resolve().parents[1] / 'static' / 'index.html'
+    return path.read_text(encoding='utf-8')
+
+
+def _function_source(page: str, name: str) -> str:
+    body = page.split(f'function {name}(', 1)[1]
+    return body.split('\n}\n', 1)[0]
+
+
+def test_frontend_offers_all_three_corpora() -> None:
+    page = _page()
+
+    assert '<option value="models" selected>Models</option>' in page
+    assert '<option value="kernels">Kernels</option>' in page
+    assert '<option value="docker">Docker Images</option>' in page
+
+
+def test_frontend_tracks_docker_in_every_corpus_state_map() -> None:
+    page = _page()
+
+    assert 'facets: { models: null, kernels: null, docker: null }' in page
+    assert 'ready: { models: false, kernels: false, docker: false }' in page
+    assert 'loading: { models: null, kernels: null, docker: null }' in page
+    assert 'docker: {' in page.split('sel: {', 1)[1]
+
+
+def test_frontend_checks_model_exclusions_by_default() -> None:
+    page = _page()
+
+    declaration = re.search(
+        r'const DEFAULT_EXCLUDED_FAMILIES = \[(.*?)\];', page, re.S)
+    assert declaration is not None
+    assert re.findall(r"'([a-z]+)'", declaration.group(1)) == list(
+        DEFAULT_EXCLUDED_FAMILIES)
+
+    # Checked means hidden, and both exclusions start on for the browser only.
+    assert 'excludedFamilies: new Set(DEFAULT_EXCLUDED_FAMILIES)' in page
+    assert 'excludeQuantizations: true' in page
+    assert 'exclude_families: [...state.sel.models.excludedFamilies]' in page
+    assert ('exclude_quantizations: state.sel.models.excludeQuantizations'
+            in page)
+
+
+def test_frontend_restores_default_exclusions_when_clearing_the_deck() -> None:
+    page = _page()
+    source = _function_source(page, 'clearModels')
+
+    # `clear the deck` restores the product defaults; it must not switch the
+    # exclusions off, which would silently widen every subsequent search.
+    assert 'DEFAULT_EXCLUDED_FAMILIES' in source
+    assert 'excludeQuantizations = true' in source
+
+
+def test_frontend_keeps_model_size_as_precise_billion_boxes() -> None:
+    page = _page()
+
+    assert 'id="f-pmin"' in page and 'id="f-pmax"' in page
+    assert page.count('step="0.1"') == 2
+    assert 'Model size (billions)' in page
+    assert '1.5B–3.5B' in page
+    assert '* 1e9' in page
+    # An inverted range is flagged rather than sent as an impossible request.
+    assert 'id="size-warn"' in page
+
+
+def test_frontend_defaults_docker_to_recipes_with_an_archive_toggle() -> None:
+    page = _page()
+    source = _function_source(page, 'buildDockerReq')
+
+    assert 'includeArchives: false' in page
+    assert 'id="d-archives"' in page
+    assert "filters.artifact_kinds = ['recipe']" in source
+    # Enabling archives removes the constraint instead of adding a second kind.
+    assert 'if (!s.includeArchives)' in source
+    assert "'archive'" not in source
+
+
+def test_frontend_routes_every_corpus_through_one_url_builder() -> None:
+    page = _page()
+
+    assert ("const resultKey = {models:'models', kernels:'kernels', "
+            "docker:'containers'}" in page)
+    assert 'const endpoint = (kind, corpus) =>' in page
+    # No binary ternary may survive, or Docker silently routes to kernels.
+    assert "'/api/search?corpus=kernels'" not in page
+    assert "'/api/facets?corpus=kernels'" not in page
+
+
+def test_frontend_escapes_every_docker_card_value() -> None:
+    page = _page()
+    source = _function_source(page, 'dockerCard')
+
+    assert 'esc(' in source
+    # No raw record field may reach the template unescaped.
+    assert re.search(r'\$\{c\.[A-Za-z_]+\}', source) is None
+
+
+def test_frontend_links_docker_artifacts_to_valid_hugging_face_targets() -> None:
+    page = _page()
+    source = _function_source(page, 'containerHref')
+
+    assert "'spaces/'" in source and "'datasets/'" in source
+    assert 'blob/' in source
+    # Bucket rows and synthetic <recipe> paths have no blob URL; those fall
+    # back to the repository landing page instead of a 404.
+    assert '<recipe>' in source

tests/test_search_indexes.py

@@ -0,0 +1,1287 @@
+"""Tests for the reusable multi-corpus index core (bsides.search_indexes).
+
+Covers the loader validation contract, the registry's failure isolation,
+the ModelAdapter (today's model behavior, relocated), and the shared
+ranking functions. Fixtures write real `meta.sqlite` + `embeddings.f16.npy`
+pairs to tmp dirs so the loader is exercised exactly as on the Space.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from pathlib import Path
+from types import SimpleNamespace
+
+import numpy as np
+import pytest
+
+from bsides.search_indexes import (
+    MAX_QUERY_CHARS,
+    MATRIX_NAME,
+    SQLITE_NAME,
+    IndexRegistry,
+    IndexSpec,
+    LoadedIndex,
+    ModelAdapter,
+    SearchReq,
+    UnavailableError,
+    download_index,
+    embed_query,
+    semantic_rank,
+    structured_page,
+)
+
+# CARD_COLS + created_at (needed by the sort paths), matching the published
+# models schema subset the app actually reads.
+MODEL_DDL = """
+CREATE TABLE models (
+    row INTEGER PRIMARY KEY,
+    model_id TEXT NOT NULL UNIQUE,
+    author TEXT,
+    month TEXT,
+    created_at TEXT,
+    downloads INTEGER,
+    likes INTEGER,
+    tags TEXT,
+    base_model TEXT,
+    relation TEXT,
+    license TEXT,
+    params INTEGER,
+    model_type TEXT,
+    architectures TEXT,
+    context_len INTEGER,
+    num_experts INTEGER,
+    code_imports TEXT,
+    gated INTEGER,
+    config TEXT
+);
+"""
+
+KERNEL_DDL = """
+CREATE TABLE kernels (
+    row INTEGER PRIMARY KEY, repo_id TEXT NOT NULL UNIQUE, author TEXT,
+    created_at TEXT, month TEXT, last_modified TEXT, downloads INTEGER,
+    likes INTEGER, tags TEXT, languages TEXT, accelerators TEXT,
+    torch_versions TEXT, cuda_archs TEXT, cpu_archs TEXT,
+    operating_systems TEXT, dtypes TEXT, intrinsics TEXT, kernel_names TEXT,
+    torch_ops TEXT, build_variants TEXT, variant_count INTEGER,
+    has_build_dir INTEGER, source_files INTEGER, document TEXT
+);
+"""
+
+CONTAINER_DDL = """
+CREATE TABLE containers (
+ row INTEGER PRIMARY KEY, repo_id TEXT NOT NULL, repo_type TEXT NOT NULL,
+ artifact_path TEXT NOT NULL, artifact_kind TEXT NOT NULL,
+ author TEXT, sha TEXT NOT NULL, created_at TEXT, last_modified TEXT,
+ downloads INTEGER, likes INTEGER, tags TEXT, description TEXT,
+ artifact_files TEXT, qualification_reasons TEXT, base_images TEXT,
+ accelerators TEXT, cuda_versions TEXT, rocm_versions TEXT, python_versions TEXT,
+ node_versions TEXT, operating_systems TEXT, ports TEXT, services TEXT,
+ package_managers TEXT, frameworks TEXT, entrypoints TEXT, commands TEXT,
+ has_compose INTEGER, has_devcontainer INTEGER, has_multistage INTEGER,
+ source_files INTEGER, source_bytes INTEGER, document TEXT, document_hash TEXT
+);
+"""
+
+
+def model_row(row, model_id, *, author='indie', month='2024-01',
+              created_at='2024-01-15T00:00:00Z', downloads=0, likes=0,
+              tags='[]', base_model=None, relation=None, license=None,
+              params=None, model_type=None, architectures=None,
+              context_len=None, num_experts=None, code_imports=None,
+              gated=0, config=None):
+    return (row, model_id, author, month, created_at, downloads, likes, tags,
+            base_model, relation, license, params, model_type, architectures,
+            context_len, num_experts, code_imports, gated, config)
+
+
+def kernel_row(row, repo_id, *, author='alice', month='2025-01',
+               created_at='2025-01-15T00:00:00Z', downloads=100, likes=2,
+               tags='["kernels"]', languages='["cuda","python"]',
+               accelerators='["nvidia"]', torch_versions='["2.5"]',
+               cuda_archs='["sm_90"]', cpu_archs='[]',
+               operating_systems='["linux"]', dtypes='["bf16","fp16"]',
+               intrinsics='["mma_sync","__syncthreads"]',
+               kernel_names='["fused_gemm"]', torch_ops='["matmul"]',
+               build_variants='["torch25-cu124"]', variant_count=3,
+               has_build_dir=1, source_files=4, document='fused gemm kernel'):
+    return (row, repo_id, author, created_at, month, created_at, downloads,
+            likes, tags, languages, accelerators, torch_versions, cuda_archs,
+            cpu_archs, operating_systems, dtypes, intrinsics, kernel_names,
+            torch_ops, build_variants, variant_count, has_build_dir,
+            source_files, document)
+
+
+def _json_text(value):
+    return json.dumps(value)
+
+
+def container_row(
+        row, repo_id, *, repo_type='model', artifact_path='Dockerfile',
+        artifact_kind='recipe', author='alice', sha='sha-1',
+        created_at='2025-01-15T00:00:00Z',
+        last_modified='2025-01-16T00:00:00Z', downloads=100, likes=2,
+        tags=None, description='container recipe', artifact_files=None,
+        qualification_reasons=None, base_images=None, accelerators=None,
+        cuda_versions=None, rocm_versions=None, python_versions=None,
+        node_versions=None, operating_systems=None, ports=None, services=None,
+        package_managers=None, frameworks=None, entrypoints=None,
+        commands=None, has_compose=0, has_devcontainer=0, has_multistage=0,
+        source_files=4, source_bytes=1024, document='container search doc',
+        document_hash='hash-1'):
+    return (
+        row, repo_id, repo_type, artifact_path, artifact_kind, author, sha,
+        created_at, last_modified, downloads, likes,
+        _json_text(tags or []), description, _json_text(artifact_files or []),
+        _json_text(qualification_reasons or []), _json_text(base_images or []),
+        _json_text(accelerators or []), _json_text(cuda_versions or []),
+        _json_text(rocm_versions or []), _json_text(python_versions or []),
+        _json_text(node_versions or []),
+        _json_text(operating_systems or []), _json_text(ports or []),
+        _json_text(services or []), _json_text(package_managers or []),
+        _json_text(frameworks or []), _json_text(entrypoints or []),
+        _json_text(commands or []), has_compose, has_devcontainer,
+        has_multistage, source_files, source_bytes, document, document_hash,
+    )
+
+
+def basis(n, dim=4):
+    """n normalized basis vectors (row i -> dimension i % dim)."""
+    m = np.zeros((n, dim), dtype=np.float32)
+    for i in range(n):
+        m[i, i % dim] = 1.0
+    return m
+
+
+def write_model_db(dir_path, rows):
+    conn = sqlite3.connect(Path(dir_path) / SQLITE_NAME)
+    conn.executescript(MODEL_DDL)
+    conn.executemany(
+        f"INSERT INTO models VALUES ({','.join('?' * 19)})", rows)
+    conn.commit()
+    conn.close()
+
+
+def write_matrix(dir_path, vectors):
+    np.save(Path(dir_path) / MATRIX_NAME, vectors.astype(np.float16))
+
+
+def write_kernel_db(dir_path, rows):
+    conn = sqlite3.connect(Path(dir_path) / SQLITE_NAME)
+    conn.executescript(KERNEL_DDL)
+    conn.executemany(
+        f"INSERT INTO kernels VALUES ({','.join('?' * 24)})", rows)
+    conn.commit()
+    conn.close()
+
+
+def write_container_db(dir_path, rows):
+    conn = sqlite3.connect(Path(dir_path) / SQLITE_NAME)
+    conn.executescript(CONTAINER_DDL)
+    conn.executemany(
+        f"INSERT INTO containers VALUES ({','.join('?' * 35)})", rows)
+    conn.commit()
+    conn.close()
+
+
+def write_index_dir(dir_path, rows, vectors):
+    write_model_db(dir_path, rows)
+    write_matrix(dir_path, vectors)
+
+
+def make_spec(local_dir, **overrides):
+    base = dict(
+        key='models',
+        dataset_id='owner/corpus',
+        local_dir=Path(local_dir),
+        table='models',
+        id_column='model_id',
+        embed_model='text-embedding-3-small',
+        dimensions=4,
+    )
+    base.update(overrides)
+    return IndexSpec(**base)
+
+
+FIXTURE_ROWS = [
+    model_row(0, 'indie/alpha', downloads=10, likes=1, tags='["llama","sft"]',
+              model_type='llama', license='mit', relation='finetune',
+              base_model='meta-llama/Llama-3-8B', month='2024-01',
+              created_at='2024-01-10T00:00:00Z', code_imports='["flash_attn"]',
+              architectures='["LlamaForCausalLM"]', params=8_000_000_000,
+              context_len=8192),
+    model_row(1, 'indie/beta', author='lab', downloads=500, likes=9,
+              tags='["mamba"]', model_type='mamba', license='apache-2.0',
+              month='2025-02', created_at='2025-02-02T00:00:00Z'),
+    model_row(2, 'indie/gamma', downloads=50, likes=3, tags='["qwen2","dpo"]',
+              model_type='qwen2', month='2024-03',
+              created_at='2024-03-05T00:00:00Z', num_experts=8,
+              code_imports='["triton"]', gated=1),
+]
+
+EXCLUSION_ROWS = [
+    model_row(
+        0, 'indie/llama-derivative', tags='["research"]',
+        base_model='meta-llama/Llama-3', model_type='transformer'),
+    model_row(
+        1, 'indie/qwen-tagged', tags='["Qwen3"]',
+        model_type='transformer'),
+    model_row(
+        2, 'indie/mistral-architecture',
+        architectures='["MistralForCausalLM"]', model_type='transformer'),
+    model_row(
+        3, 'indie/gptq-repack', tags='["gptq"]',
+        config='{"quantization_config": {"bits": 4}}'),
+    model_row(
+        4, 'indie/native-fp8-research', tags='["fp8"]',
+        model_type='research', config='{"torch_dtype": "float8_e4m3fn"}'),
+    model_row(
+        5, 'indie/native-int8-research', tags='["int8"]',
+        model_type='research', config='{"torch_dtype": "int8"}'),
+    model_row(
+        6, 'indie/config-null-quant', model_type='research',
+        config='{"quantization_config": null}'),
+    model_row(
+        7, 'indie/malformed-config', model_type='research',
+        config='not-json'),
+]
+
+KERNEL_ROWS = [
+    kernel_row(0, 'alice/fused-gemm'),
+    kernel_row(
+        1, 'bob/paged-attention', author='bob', month='2024-06',
+        created_at='2024-06-02T00:00:00Z', downloads=20, likes=8,
+        languages='["triton","python"]', torch_versions='["2.4"]',
+        cuda_archs='["sm_80"]', dtypes='["fp32"]',
+        intrinsics='["tl.dot"]', kernel_names='["paged_attention"]',
+        torch_ops='["attention"]', build_variants='[]', variant_count=1,
+        has_build_dir=0, source_files=2, document='paged attention kernel'),
+    kernel_row(
+        2, 'alice/int8-conv', month='2025-02',
+        created_at='2025-02-03T00:00:00Z', downloads=500, likes=5,
+        languages='["cpp"]', accelerators='["amd"]',
+        torch_versions='["2.5"]', cuda_archs='[]', cpu_archs='["x86_64"]',
+        dtypes='["int8"]', intrinsics='["avx2"]',
+        kernel_names='["int8_conv"]', torch_ops='["conv2d"]',
+        build_variants='["rocm"]', variant_count=5, has_build_dir=1,
+        source_files=6, document='int8 convolution kernel'),
+]
+
+CONTAINER_ROWS = [
+    container_row(
+        0, 'alice/cuda-recipe', repo_type='model', artifact_path='Dockerfile',
+        artifact_kind='recipe', author='alice', sha='sha-cuda',
+        created_at='2025-02-01T00:00:00Z',
+        last_modified='2025-02-02T00:00:00Z', downloads=300, likes=9,
+        tags=['docker', 'cuda'], description='CUDA PyTorch recipe',
+        artifact_files=['Dockerfile'],
+        qualification_reasons=['dockerfile', 'dependencies'],
+        base_images=['nvidia/cuda:12.8.0-runtime-ubuntu22.04'],
+        accelerators=['nvidia'], cuda_versions=['12.8'], rocm_versions=[],
+        python_versions=['3.11'], node_versions=[],
+        operating_systems=['ubuntu22.04'], ports=['7860'], services=['api'],
+        package_managers=['pip'], frameworks=['pytorch'],
+        entrypoints=['python app.py'], commands=['uvicorn app:app'],
+        has_compose=0, has_devcontainer=0, has_multistage=1, source_files=6,
+        source_bytes=4096,
+        document='python 3.11 cuda 12.8 pytorch recipe',
+        document_hash='hash-cuda'),
+    container_row(
+        1, 'bob/rocm-recipe', repo_type='space',
+        artifact_path='docker/Dockerfile', artifact_kind='recipe',
+        author='bob', sha='sha-rocm', created_at='2025-03-01T00:00:00Z',
+        last_modified='2025-03-02T00:00:00Z', downloads=120, likes=4,
+        tags=['docker', 'rocm'], description='ROCm build',
+        artifact_files=['docker/Dockerfile'],
+        qualification_reasons=['dockerfile'],
+        base_images=['rocm/pytorch:latest'], accelerators=['amd'],
+        cuda_versions=[], rocm_versions=['6.1'], python_versions=['3.12'],
+        node_versions=['20'], operating_systems=['ubuntu24.04'],
+        ports=['7860'], services=[], package_managers=['apt', 'pip'],
+        frameworks=['pytorch'], entrypoints=[], commands=['python launch.py'],
+        has_compose=0, has_devcontainer=0, has_multistage=0, source_files=5,
+        source_bytes=3072, document='python 3.12 rocm pytorch recipe',
+        document_hash='hash-rocm'),
+    container_row(
+        2, 'carol/compose-stack', repo_type='dataset',
+        artifact_path='compose/Dockerfile', artifact_kind='recipe',
+        author='carol', sha='sha-compose', created_at='2025-04-01T00:00:00Z',
+        last_modified='2025-04-02T00:00:00Z', downloads=80, likes=6,
+        tags=['docker', 'compose'], description='Compose-backed stack',
+        artifact_files=['compose/Dockerfile', 'compose/docker-compose.yml'],
+        qualification_reasons=['compose', 'devcontainer'],
+        base_images=['python:3.10-slim'], accelerators=[],
+        cuda_versions=[], rocm_versions=[], python_versions=['3.10'],
+        node_versions=['18'], operating_systems=['debian'],
+        ports=['5432', '8888'], services=['jupyter', 'postgres'],
+        package_managers=['apt', 'pip'], frameworks=['fastapi'],
+        entrypoints=['./boot.sh'], commands=['docker compose up'],
+        has_compose=1, has_devcontainer=1, has_multistage=0, source_files=8,
+        source_bytes=8192, document='compose jupyter postgres fastapi stack',
+        document_hash='hash-compose'),
+    container_row(
+        3, 'dana/archive-bundle', repo_type='dataset',
+        artifact_path='artifacts/container.tar.gz', artifact_kind='archive',
+        author='dana', sha='sha-archive', created_at='2025-05-01T00:00:00Z',
+        last_modified='2025-05-02T00:00:00Z', downloads=40, likes=1,
+        tags=['docker', 'archive'], description='Archived CUDA image',
+        artifact_files=['artifacts/container.tar.gz'],
+        qualification_reasons=['archive'],
+        base_images=['ubuntu:22.04'], accelerators=['nvidia'],
+        cuda_versions=['12.8'], rocm_versions=[], python_versions=['3.11'],
+        node_versions=[], operating_systems=['ubuntu22.04'],
+        ports=['8080'], services=['worker'], package_managers=['pip'],
+        frameworks=['pytorch'], entrypoints=['./serve.sh'],
+        commands=['python worker.py'], has_compose=0, has_devcontainer=0,
+        has_multistage=0, source_files=2, source_bytes=2048,
+        document='python 3.11 cuda 12.8 archive image',
+        document_hash='hash-archive'),
+]
+
+
+@pytest.fixture
+def loaded_models(tmp_path):
+    write_index_dir(tmp_path, FIXTURE_ROWS, basis(3))
+    spec = make_spec(tmp_path)
+    index = LoadedIndex(spec, ModelAdapter(spec))
+    index.load()
+    assert index.ready.is_set()  # fixture sanity
+    return index
+
+
+@pytest.fixture
+def loaded_exclusion_models(tmp_path):
+    write_index_dir(tmp_path, EXCLUSION_ROWS, basis(len(EXCLUSION_ROWS)))
+    spec = make_spec(tmp_path)
+    index = LoadedIndex(spec, ModelAdapter(spec))
+    index.load()
+    assert index.ready.is_set(), index.error
+    return index
+
+
+def load_kernels(tmp_path):
+    from bsides.search_indexes import KernelAdapter
+
+    write_kernel_db(tmp_path, KERNEL_ROWS)
+    write_matrix(tmp_path, basis(3))
+    spec = make_spec(
+        tmp_path, key='kernels', dataset_id='owner/kernels', table='kernels',
+        id_column='repo_id')
+    index = LoadedIndex(spec, KernelAdapter(spec))
+    index.load()
+    assert index.ready.is_set(), index.error
+    return index
+
+
+def load_containers(tmp_path):
+    from bsides.search_indexes import ContainerAdapter
+
+    write_container_db(tmp_path, CONTAINER_ROWS)
+    write_matrix(tmp_path, basis(len(CONTAINER_ROWS)))
+    spec = make_spec(
+        tmp_path, key='docker', dataset_id='owner/containers',
+        table='containers', id_column='repo_id')
+    index = LoadedIndex(spec, ContainerAdapter(spec))
+    index.load()
+    assert index.ready.is_set(), index.error
+    return index
+
+
+@pytest.fixture
+def loaded_containers(tmp_path):
+    return load_containers(tmp_path)
+
+
+class FakeEmbeddings:
+    def __init__(self, vector):
+        self.vector = [float(v) for v in vector]
+        self.calls: list[dict] = []
+
+    def create(self, **kwargs):
+        self.calls.append(kwargs)
+        return SimpleNamespace(
+            data=[SimpleNamespace(embedding=list(self.vector))])
+
+
+class FakeClient:
+    def __init__(self, vector):
+        self.embeddings = FakeEmbeddings(vector)
+
+
+# ── download contract ─────────────────────────────────────────────────────────
+
+def test_download_index_requests_dataset_files_into_spec_dir(tmp_path):
+    spec = make_spec(tmp_path / 'idx')
+    calls: list[tuple[str, dict]] = []
+
+    def downloader(dataset_id, **kwargs):
+        calls.append((dataset_id, kwargs))
+
+    download_index(downloader, spec)
+
+    assert calls == [
+        ('owner/corpus', {
+            'repo_type': 'dataset',
+            'local_dir': tmp_path / 'idx',
+            'allow_patterns': ['embeddings.f16.npy', 'meta.sqlite'],
+        })
+    ]
+
+
+# ── loader: happy paths ───────────────────────────────────────────────────────
+
+def test_load_validates_marks_ready_and_computes_facets(loaded_models):
+    assert loaded_models.error is None
+    assert loaded_models.rows == 3
+    assert loaded_models.matrix.shape == (3, 4)
+    assert loaded_models.matrix.dtype == np.float32
+    assert loaded_models.facets['total'] == 3
+
+
+def test_load_pulls_dataset_when_files_are_missing(tmp_path):
+    src = tmp_path / 'src'
+    src.mkdir()
+    write_index_dir(src, [model_row(0, 'a/b')], basis(1))
+    spec = make_spec(tmp_path / 'idx')
+    seen: list[tuple[str, dict]] = []
+
+    def downloader(dataset_id, **kwargs):
+        seen.append((dataset_id, dict(kwargs)))
+        target = Path(kwargs['local_dir'])
+        target.mkdir(parents=True, exist_ok=True)
+        for name in kwargs['allow_patterns']:
+            (target / name).write_bytes((src / name).read_bytes())
+
+    index = LoadedIndex(spec, ModelAdapter(spec))
+    index.load(downloader)
+
+    assert seen and seen[0][0] == 'owner/corpus'
+    assert index.ready.is_set() and index.error is None and index.rows == 1
+
+
+def test_load_without_downloader_never_imports_hub_when_files_exist(tmp_path):
+    # Files already present → the lazy huggingface_hub import never runs.
+    write_index_dir(tmp_path, [model_row(0, 'a/b')], basis(1))
+    index = LoadedIndex(make_spec(tmp_path))
+    index.load()
+    assert index.ready.is_set()
+
+
+
+# ── loader: validation failures stay isolated ─────────────────────────────────
+
+def test_load_rejects_matrix_rank_not_two(tmp_path):
+    write_model_db(tmp_path, [model_row(0, 'a/b')])
+    np.save(tmp_path / MATRIX_NAME, np.zeros(4, dtype=np.float16))  # 1-D
+    index = LoadedIndex(make_spec(tmp_path))
+    index.load()
+    assert not index.ready.is_set()
+    assert index.matrix is None
+    assert index.error and 'rank' in index.error
+
+
+def test_load_rejects_dimension_mismatch(tmp_path):
+    write_model_db(tmp_path, [model_row(0, 'a/b')])
+    write_matrix(tmp_path, basis(1, dim=8))  # spec expects 4
+    index = LoadedIndex(make_spec(tmp_path))
+    index.load()
+    assert not index.ready.is_set()
+    assert index.error and 'dimensions' in index.error
+
+
+def test_load_rejects_non_finite_values(tmp_path):
+    write_model_db(tmp_path, [model_row(0, 'a/b')])
+    m = basis(1)
+    m[0, 0] = np.inf
+    write_matrix(tmp_path, m)
+    index = LoadedIndex(make_spec(tmp_path))
+    index.load()
+    assert not index.ready.is_set()
+    assert index.error and 'non-finite' in index.error
+
+
+def test_load_rejects_sqlite_that_fails_quick_check(tmp_path):
+    (tmp_path / SQLITE_NAME).write_bytes(b'this is not a sqlite database')
+    write_matrix(tmp_path, basis(1))
+    index = LoadedIndex(make_spec(tmp_path))
+    index.load()
+    assert not index.ready.is_set()
+    assert index.error
+
+
+def test_load_rejects_row_count_mismatch(tmp_path):
+    write_model_db(tmp_path, [model_row(0, 'a/b')])
+    write_matrix(tmp_path, basis(2))
+    index = LoadedIndex(make_spec(tmp_path))
+    index.load()
+    assert not index.ready.is_set()
+    assert index.error and 'rows' in index.error
+
+
+def test_load_rejects_rows_outside_matrix_bounds(tmp_path):
+    write_model_db(tmp_path,
+                   [model_row(0, 'a/b'), model_row(5, 'c/d')])  # row 5 >= N=2
+    write_matrix(tmp_path, basis(2))
+    index = LoadedIndex(make_spec(tmp_path))
+    index.load()
+    assert not index.ready.is_set()
+    assert index.error and 'bounds' in index.error
+
+
+def test_load_accepts_empty_index(tmp_path):
+    write_model_db(tmp_path, [])
+    write_matrix(tmp_path, np.zeros((0, 4), dtype=np.float32))
+    index = LoadedIndex(make_spec(tmp_path))
+    index.load()
+    assert index.ready.is_set() and index.rows == 0
+
+
+def test_load_isolates_downloader_failure(tmp_path):
+    def downloader(dataset_id, **kwargs):
+        raise RuntimeError('hub says no')
+
+    index = LoadedIndex(make_spec(tmp_path))
+    index.load(downloader)
+    assert not index.ready.is_set()
+    assert index.error and 'hub says no' in index.error
+
+
+
+# ── reload: hot-swap contract ─────────────────────────────────────────────────
+
+def republish(dir_path, rows, vectors):
+    """A downloader that replaces the corpus files, like a fresh publish."""
+    def downloader(dataset_id, **kwargs):
+        target = Path(kwargs['local_dir'])
+        for name in (SQLITE_NAME, MATRIX_NAME):
+            (target / name).unlink(missing_ok=True)
+        write_index_dir(target, rows, vectors)
+    return downloader
+
+
+def test_reload_swaps_in_the_freshly_published_index(loaded_models):
+    assert loaded_models.rows == 3
+
+    swapped = loaded_models.reload(republish(
+        loaded_models.spec.local_dir,
+        [model_row(0, 'indie/delta', tags='["rwkv"]', model_type='rwkv'),
+         model_row(1, 'indie/epsilon', tags='["mamba"]', model_type='mamba')],
+        basis(2)))
+
+    assert swapped is True
+    assert loaded_models.error is None
+    assert loaded_models.ready.is_set()
+    assert loaded_models.rows == 2
+    assert loaded_models.matrix.shape == (2, 4)
+    ids = [r[0] for r in loaded_models.db().execute(
+        'SELECT model_id FROM models ORDER BY row')]
+    assert ids == ['indie/delta', 'indie/epsilon']
+    assert loaded_models.facets['total'] == 2
+    assert {a['v'] for a in loaded_models.facets['archs']} == {'rwkv', 'mamba'}
+
+
+def test_reload_invalidates_connections_to_the_replaced_file(loaded_models):
+    stale = loaded_models.db()
+    generation = loaded_models.generation
+
+    loaded_models.reload(republish(
+        loaded_models.spec.local_dir,
+        [model_row(0, 'indie/delta')], basis(1)))
+
+    assert loaded_models.generation > generation
+    fresh = loaded_models.db()
+    assert fresh is not stale
+    assert fresh.execute(
+        'SELECT model_id FROM models').fetchone()[0] == 'indie/delta'
+
+
+def test_reload_does_not_skip_the_download_step(loaded_models):
+    # load() skips the downloader call when files exist; reload() must not, or
+    # a newly published revision would never be checked for changed files.
+    seen: list[str] = []
+
+    def downloader(dataset_id, **kwargs):
+        seen.append(dataset_id)
+
+    assert loaded_models.reload(downloader) is True
+    assert seen == ['owner/corpus']
+
+
+def test_failed_download_keeps_serving_the_previous_index(loaded_models):
+    def downloader(dataset_id, **kwargs):
+        raise RuntimeError('hub says no')
+
+    assert loaded_models.reload(downloader) is False
+    assert loaded_models.ready.is_set()          # never went down
+    assert loaded_models.rows == 3
+    assert loaded_models.matrix.shape == (3, 4)
+    assert loaded_models.facets['total'] == 3
+    assert 'hub says no' in loaded_models.error
+    assert loaded_models.db().execute(
+        'SELECT COUNT(*) FROM models').fetchone()[0] == 3
+
+
+def test_reload_rejecting_a_bad_publish_keeps_serving_the_old_index(
+        loaded_models):
+    # A published matrix at the wrong width must not replace a good one.
+    assert loaded_models.reload(republish(
+        loaded_models.spec.local_dir,
+        [model_row(0, 'indie/delta')], basis(1, dim=8))) is False
+
+    assert loaded_models.ready.is_set()
+    assert loaded_models.rows == 3
+    assert loaded_models.matrix.shape == (3, 4)
+    assert 'dimensions' in loaded_models.error
+
+
+def test_reload_rejects_a_publish_whose_rows_do_not_match_the_matrix(
+        loaded_models):
+    assert loaded_models.reload(republish(
+        loaded_models.spec.local_dir,
+        [model_row(0, 'indie/delta')], basis(2))) is False
+
+    assert loaded_models.ready.is_set() and loaded_models.rows == 3
+    assert 'rows' in loaded_models.error
+
+
+# ── registry ──────────────────────────────────────────────────────────────────
+
+def test_registry_isolates_a_broken_corpus_from_a_healthy_one(tmp_path):
+    good_dir, bad_dir = tmp_path / 'good', tmp_path / 'bad'
+    good_dir.mkdir()
+    bad_dir.mkdir()
+    write_index_dir(good_dir, FIXTURE_ROWS, basis(3))
+    write_model_db(bad_dir, [model_row(0, 'a/b')])
+    write_matrix(bad_dir, basis(1, dim=8))  # wrong dims → validation failure
+
+    registry = IndexRegistry()
+    registry.register(ModelAdapter(make_spec(good_dir, key='models')))
+    registry.register(ModelAdapter(make_spec(bad_dir, key='kernels')))
+    registry.load_all()  # must not raise
+
+    assert registry.index('models').ready.is_set()
+    bad = registry.index('kernels')
+    assert not bad.ready.is_set() and bad.error
+
+    status = registry.status()
+    assert status['models']['ready'] is True
+    assert status['models']['rows'] == 3
+    assert status['models']['error'] is None
+    assert status['kernels']['ready'] is False
+    assert status['kernels']['error']
+
+
+def test_registry_unknown_key_raises_keyerror():
+    with pytest.raises(KeyError):
+        IndexRegistry().index('bogus')
+
+
+def test_registry_start_loading_runs_isolated_threads(tmp_path):
+    good_dir = tmp_path / 'good'
+    good_dir.mkdir()
+    write_index_dir(good_dir, FIXTURE_ROWS, basis(3))
+    registry = IndexRegistry()
+    registry.register(ModelAdapter(make_spec(good_dir, key='models')))
+    registry.start_loading()
+    index = registry.index('models')
+    assert index.ready.wait(timeout=10)
+    assert index.error is None
+
+
+# ── LoadedIndex connections ───────────────────────────────────────────────────
+
+def test_db_is_thread_local_readonly_and_generation_scoped(loaded_models):
+    conn = loaded_models.db()
+    assert conn is loaded_models.db()  # same thread → same connection
+    with pytest.raises(sqlite3.OperationalError):
+        conn.execute('CREATE TABLE hack (x INTEGER)')
+
+    loaded_models.invalidate_connections()
+    fresh = loaded_models.db()
+    assert fresh is not conn
+    assert fresh.execute('SELECT COUNT(*) FROM models').fetchone()[0] == 3
+
+
+# ── query embedding ───────────────────────────────────────────────────────────
+
+def test_embed_query_uses_spec_model_and_selected_matrix_dimensions(
+        loaded_models):
+    client = FakeClient([2.0, 0.0, 0.0, 0.0])
+    vector = embed_query(loaded_models, client, 'odd attention')
+
+    assert vector.shape == (4,)
+    assert np.isclose(np.linalg.norm(vector), 1.0)
+    assert client.embeddings.calls == [{
+        'model': 'text-embedding-3-small',
+        'dimensions': 4,
+        'input': 'odd attention',
+    }]
+
+
+def test_embed_query_caps_input_at_max_chars(loaded_models):
+    client = FakeClient([1, 0, 0, 0])
+    embed_query(loaded_models, client, 'x' * (MAX_QUERY_CHARS + 250))
+    assert len(client.embeddings.calls[0]['input']) == MAX_QUERY_CHARS
+
+
+def test_embed_query_without_client_names_the_selected_credential(loaded_models):
+    with pytest.raises(
+            UnavailableError, match='no OPENAI_KERNEL_API_KEY'):
+        embed_query(
+            loaded_models, None, 'q',
+            credential_name='OPENAI_KERNEL_API_KEY')
+
+
+def test_embed_query_without_matrix_is_unavailable(tmp_path):
+    index = LoadedIndex(make_spec(tmp_path))
+    with pytest.raises(UnavailableError, match='index not loaded'):
+        embed_query(index, FakeClient([1, 0, 0, 0]), 'q')
+
+
+
+# ── shared semantic ranking ───────────────────────────────────────────────────
+
+def test_semantic_rank_scores_orders_and_paginates(loaded_models):
+    client = FakeClient([0.2, 1.0, 0.5, 0.0])  # beta > gamma > alpha
+    total, cards = semantic_rank(
+        loaded_models.db(), loaded_models, loaded_models.adapter,
+        where='1=1', args=[], sem_q='mamba hybrid', page=0, page_size=2,
+        embed_client=client)
+
+    assert total == 3
+    assert [c['model_id'] for c in cards] == ['indie/beta', 'indie/gamma']
+    assert cards[0]['score'] > cards[1]['score']
+    assert cards[0]['tags'] == ['mamba']  # JSON columns decoded
+
+
+def test_semantic_rank_uses_candidate_scoring_for_small_filtered_sets(
+        loaded_models):
+    # total=1 < N//2 → MAT[rows] @ qv branch instead of (MAT @ qv)[rows]
+    client = FakeClient([0.0, 0.0, 1.0, 0.0])
+    total, cards = semantic_rank(
+        loaded_models.db(), loaded_models, loaded_models.adapter,
+        where='model_id = ?', args=['indie/gamma'], sem_q='q',
+        page=0, page_size=24, embed_client=client)
+
+    assert total == 1
+    assert [c['model_id'] for c in cards] == ['indie/gamma']
+    assert cards[0]['score'] == 1.0
+
+
+def test_semantic_rank_empty_candidates_skip_embedding(loaded_models):
+    client = FakeClient([1, 0, 0, 0])
+    total, cards = semantic_rank(
+        loaded_models.db(), loaded_models, loaded_models.adapter,
+        where='row < 0', args=[], sem_q='q', page=0, page_size=24,
+        embed_client=client)
+
+    assert (total, cards) == (0, [])
+    assert client.embeddings.calls == []
+
+
+def test_semantic_rank_page_beyond_window_returns_total_but_no_cards(
+        loaded_models):
+    client = FakeClient([1, 0, 0, 0])
+    total, cards = semantic_rank(
+        loaded_models.db(), loaded_models, loaded_models.adapter,
+        where='1=1', args=[], sem_q='q', page=3, page_size=2,
+        embed_client=client)
+
+    assert total == 3 and cards == []
+
+
+def test_semantic_rank_propagates_unavailable_embedding(loaded_models):
+    with pytest.raises(UnavailableError):
+        semantic_rank(
+            loaded_models.db(), loaded_models, loaded_models.adapter,
+            where='1=1', args=[], sem_q='q', page=0, page_size=2,
+            embed_client=None)
+
+
+# ── shared structured paging ──────────────────────────────────────────────────
+
+def test_structured_page_orders_counts_and_paginates(loaded_models):
+    total, cards = structured_page(
+        loaded_models.db(), loaded_models, loaded_models.adapter,
+        where='1=1', args=[], sort='downloads', page=0, page_size=2)
+
+    assert total == 3
+    assert [c['model_id'] for c in cards] == ['indie/beta', 'indie/gamma']
+
+    total2, cards2 = structured_page(
+        loaded_models.db(), loaded_models, loaded_models.adapter,
+        where='1=1', args=[], sort='downloads', page=1, page_size=2)
+    assert total2 == 3
+    assert [c['model_id'] for c in cards2] == ['indie/alpha']
+
+
+def test_structured_page_unknown_sort_falls_back_to_newest(loaded_models):
+    total, cards = structured_page(
+        loaded_models.db(), loaded_models, loaded_models.adapter,
+        where='1=1', args=[], sort='relevance', page=0, page_size=24)
+
+    assert total == 3
+    assert [c['model_id'] for c in cards] == [
+        'indie/beta', 'indie/gamma', 'indie/alpha']  # created_at DESC
+
+
+
+# ── ModelAdapter: request parsing ─────────────────────────────────────────────
+
+def test_extract_constraints_pulls_dates_params_downloads_and_flags(
+        loaded_models):
+    r = SearchReq(query='mamba hybrid feb 2025 under 3b params '
+                        '10-50 downloads dpo custom code')
+    sem_q = loaded_models.adapter.extract_constraints(r)
+
+    assert r.month_from == r.month_to == '2025-02'
+    assert r.params_max == 3_000_000_000
+    assert r.downloads_min == 10 and r.downloads_max == 50
+    assert r.custom_code_only is True
+    assert 'dpo' in r.methods
+    # constraints leave the embedding text; meaning stays
+    assert 'feb' not in sem_q and '2025' not in sem_q
+    assert 'mamba' in sem_q and 'hybrid' in sem_q and 'dpo' in sem_q
+
+
+def test_extract_constraints_never_loosens_explicit_filters(loaded_models):
+    r = SearchReq(query='2024 mamba', month_from='2023-06', methods=['sft'])
+    loaded_models.adapter.extract_constraints(r)
+
+    assert r.month_from == '2023-06'   # explicit value untouched
+    assert r.month_to == '2024-12'     # empty slot filled
+    assert r.methods == ['sft']
+
+
+def test_extract_constraints_empty_remainder_skips_embedding(loaded_models):
+    r = SearchReq(query='under 3b params')
+    assert loaded_models.adapter.extract_constraints(r) == ''
+    assert r.params_max == 3_000_000_000
+
+
+# ── ModelAdapter: filtering, serialization, facets ────────────────────────────
+
+def test_model_adapter_exposes_spec_result_key_and_card_columns(loaded_models):
+    adapter = loaded_models.adapter
+    assert adapter.result_key == 'models'
+    assert adapter.card_columns == (
+        'row, model_id, author, month, downloads, likes, tags, base_model, '
+        'relation, license, params, model_type, architectures, context_len, '
+        'num_experts, code_imports, gated')
+    assert adapter.sort_order('downloads') == 'downloads DESC'
+    assert adapter.sort_order('bogus') == 'created_at DESC'
+
+
+def test_build_where_empty_request_is_neutral(loaded_models):
+    where, args = loaded_models.adapter.build_where(SearchReq())
+    assert where == '1=1' and args == []
+
+
+def test_model_exclusions_match_family_evidence(loaded_exclusion_models):
+    request = SearchReq(exclude_families=['llama', 'qwen'])
+    where, args = loaded_exclusion_models.adapter.build_where(request)
+    ids = [r[0] for r in loaded_exclusion_models.db().execute(
+        f'SELECT model_id FROM models WHERE {where}', args)]
+
+    assert 'indie/llama-derivative' not in ids
+    assert 'indie/qwen-tagged' not in ids
+    assert 'indie/mistral-architecture' in ids
+
+
+def test_model_family_exclusion_matches_expanded_mistral_terms(
+        loaded_exclusion_models):
+    where, args = loaded_exclusion_models.adapter.build_where(
+        SearchReq(exclude_families=['mistral']))
+    ids = [r[0] for r in loaded_exclusion_models.db().execute(
+        f'SELECT model_id FROM models WHERE {where}', args)]
+
+    assert 'indie/mistral-architecture' not in ids
+
+
+def test_quantization_exclusion_requires_strong_evidence(
+        loaded_exclusion_models):
+    request = SearchReq(exclude_quantizations=True)
+    where, args = loaded_exclusion_models.adapter.build_where(request)
+    ids = [r[0] for r in loaded_exclusion_models.db().execute(
+        f'SELECT model_id FROM models WHERE {where}', args)]
+
+    assert 'indie/gptq-repack' not in ids
+    assert 'indie/native-fp8-research' in ids
+    assert 'indie/native-int8-research' in ids
+    assert 'indie/config-null-quant' in ids
+    assert 'indie/malformed-config' in ids
+
+
+def test_malformed_config_remains_searchable_during_quantization_exclusion(
+        loaded_exclusion_models):
+    request = SearchReq(exclude_quantizations=True)
+    where, args = loaded_exclusion_models.adapter.build_where(request)
+    assert (
+        "CASE WHEN json_valid(config) "
+        "THEN json_extract(config, '$.quantization_config') IS NOT NULL "
+        "ELSE 0 END" in where)
+    ids = [r[0] for r in loaded_exclusion_models.db().execute(
+        f'SELECT model_id FROM models WHERE {where}', args)]
+
+    assert 'indie/malformed-config' in ids
+
+
+def test_model_exclusions_are_neutral_by_default(loaded_models):
+    request = SearchReq()
+
+    assert request.exclude_families == []
+    assert request.exclude_quantizations is False
+    where, args = loaded_models.adapter.build_where(request)
+    assert where == '1=1'
+    assert args == []
+
+
+def test_build_where_covers_every_model_filter(loaded_models):
+    r = SearchReq(
+        month_from='2024-01', month_to='2024-12', archs=['mamba', 'llama'],
+        methods=['sft'], relation='finetune', base_model='llama',
+        author='indie', license='mit', imports=['flash_attn'],
+        params_min=1, params_max=2, context_min=4096, downloads_min=5,
+        downloads_max=50, moe_only=True, custom_code_only=True,
+        config_contains='rope')
+    where, args = loaded_models.adapter.build_where(r)
+
+    assert where == (
+        '1=1 AND month >= ? AND month <= ? '
+        'AND ((model_type = ? OR tags LIKE ?) OR (model_type = ? OR tags LIKE ?)) '
+        'AND tags LIKE ? AND relation = ? AND base_model LIKE ? AND author LIKE ? '
+        'AND license = ? AND code_imports LIKE ? AND params >= ? AND params <= ? '
+        'AND context_len >= ? AND downloads >= ? AND downloads <= ? '
+        'AND num_experts > 1 '
+        "AND (code_imports IS NOT NULL OR tags LIKE '%\"custom_code\"%') "
+        'AND config LIKE ?')
+    assert args == ['2024-01', '2024-12', 'mamba', '%"mamba"%', 'llama',
+                    '%"llama"%', '%"sft"%', 'finetune', '%llama%', '%indie%',
+                    'mit', '%"flash_attn"%', 1, 2, 4096, 5, 50, '%rope%']
+
+
+def test_build_where_executes_against_real_sqlite(loaded_models):
+    where, args = loaded_models.adapter.build_where(SearchReq(archs=['mamba']))
+    n = loaded_models.db().execute(
+        f'SELECT COUNT(*) FROM models WHERE {where}', args).fetchone()[0]
+    assert n == 1
+
+
+def test_card_decodes_json_columns_and_rounds_score(loaded_models):
+    row = loaded_models.db().execute(
+        f'SELECT {loaded_models.adapter.card_columns} FROM models '
+        'WHERE row = 0').fetchone()
+    d = loaded_models.adapter.card(row, 0.87654)
+
+    assert d['tags'] == ['llama', 'sft']
+    assert d['code_imports'] == ['flash_attn']
+    assert d['architectures'] == ['LlamaForCausalLM']
+    assert d['score'] == 0.8765
+
+
+def test_card_without_score_omits_it(loaded_models):
+    row = loaded_models.db().execute(
+        f'SELECT {loaded_models.adapter.card_columns} FROM models '
+        'WHERE row = 1').fetchone()
+    assert 'score' not in loaded_models.adapter.card(row)
+
+
+def test_compute_facets_shape_matches_the_legacy_payload(loaded_models):
+    f = loaded_models.facets
+
+    assert f['total'] == 3
+    assert f['months'] == ['2024-01', '2024-03', '2025-02']
+    assert f['enriched'] is True
+    assert {a['v']: a['n'] for a in f['archs']} == {
+        'llama': 1, 'mamba': 1, 'qwen2': 1}
+    assert {m['v']: m['n'] for m in f['methods']} == {'sft': 1, 'dpo': 1}
+    assert {l['v'] for l in f['licenses']} == {'mit', 'apache-2.0'}
+    assert {r['v'] for r in f['relations']} == {'finetune'}
+    assert {i['v'] for i in f['imports']} == {'flash_attn', 'triton'}
+    assert {a['v'] for a in f['authors']} == {'indie', 'lab'}
+
+
+# ── KernelAdapter: isolated request, filtering, cards and facets ──────────────
+
+def test_search_request_keeps_optional_adapter_filters():
+    request = SearchReq(filters={'languages': ['cuda']})
+
+    assert request.filters == {'languages': ['cuda']}
+
+
+def test_model_adapter_ignores_adapter_filters(loaded_models):
+    request = SearchReq(filters={
+        'languages': ['cuda'], 'has_build_dir': True,
+        'variant_count_min': 99,
+    })
+
+    where, args = loaded_models.adapter.build_where(request)
+
+    assert where == '1=1'
+    assert args == []
+
+
+def test_kernel_filters_execute_against_real_sqlite(tmp_path):
+    index = load_kernels(tmp_path)
+    request = SearchReq(filters={
+        'author': 'ali',
+        'month_from': '2025-01',
+        'month_to': '2025-01',
+        'downloads_min': 50,
+        'downloads_max': 200,
+        'languages': ['cuda', 'triton'],
+        'accelerators': ['nvidia'],
+        'cuda_archs': ['sm_90'],
+        'dtypes': ['bf16'],
+        'intrinsics': ['mma_sync'],
+        'torch_ops': ['matmul'],
+        'torch_versions': ['2.5'],
+        'has_build_dir': True,
+        'variant_count_min': 3,
+        'not_a_kernel_filter': 'ignored',
+    })
+
+    where, args = index.adapter.build_where(request)
+    ids = [row[0] for row in index.db().execute(
+        f'SELECT repo_id FROM kernels WHERE {where}', args)]
+
+    assert ids == ['alice/fused-gemm']
+
+
+def test_kernel_array_filter_values_are_or_within_one_category(tmp_path):
+    index = load_kernels(tmp_path)
+    where, args = index.adapter.build_where(SearchReq(filters={
+        'languages': ['cuda', 'triton'],
+    }))
+
+    ids = [row[0] for row in index.db().execute(
+        f'SELECT repo_id FROM kernels WHERE {where} ORDER BY row', args)]
+
+    assert ids == ['alice/fused-gemm', 'bob/paged-attention']
+
+
+def test_kernel_adapter_ignores_legacy_model_and_unknown_filters(tmp_path):
+    index = load_kernels(tmp_path)
+    request = SearchReq(
+        author='nobody', downloads_min=9999, archs=['mamba'],
+        filters={'license': 'mit', 'cpu_archs': ['x86_64']})
+
+    where, args = index.adapter.build_where(request)
+    count = index.db().execute(
+        f'SELECT COUNT(*) FROM kernels WHERE {where}', args).fetchone()[0]
+
+    assert count == 3
+
+
+def test_kernel_card_decodes_arrays_and_returns_facts(tmp_path):
+    index = load_kernels(tmp_path)
+    row = index.db().execute(
+        f'SELECT {index.adapter.card_columns} FROM kernels WHERE row = 0'
+    ).fetchone()
+
+    card = index.adapter.card(row, 0.87654)
+
+    assert card['repo_id'] == 'alice/fused-gemm'
+    assert card['tags'] == ['kernels']
+    assert card['languages'] == ['cuda', 'python']
+    assert card['accelerators'] == ['nvidia']
+    assert card['torch_versions'] == ['2.5']
+    assert card['cuda_archs'] == ['sm_90']
+    assert card['cpu_archs'] == []
+    assert card['operating_systems'] == ['linux']
+    assert card['dtypes'] == ['bf16', 'fp16']
+    assert card['intrinsics'] == ['mma_sync', '__syncthreads']
+    assert card['kernel_names'] == ['fused_gemm']
+    assert card['torch_ops'] == ['matmul']
+    assert card['build_variants'] == ['torch25-cu124']
+    assert card['variant_count'] == 3
+    assert card['has_build_dir'] is True
+    assert card['source_files'] == 4
+    assert card['score'] == 0.8765
+    assert 'document' not in card
+
+
+def test_kernel_facets_count_members_of_json_arrays(tmp_path):
+    facets = load_kernels(tmp_path).facets
+
+    assert facets['total'] == 3
+    assert facets['months'] == ['2024-06', '2025-01', '2025-02']
+    assert {x['v']: x['n'] for x in facets['authors']} == {
+        'alice': 2, 'bob': 1}
+    assert {x['v']: x['n'] for x in facets['languages']} == {
+        'python': 2, 'cpp': 1, 'cuda': 1, 'triton': 1}
+    assert {x['v']: x['n'] for x in facets['accelerators']} == {
+        'nvidia': 2, 'amd': 1}
+    assert {x['v']: x['n'] for x in facets['torch_versions']} == {
+        '2.5': 2, '2.4': 1}
+    assert {x['v']: x['n'] for x in facets['cuda_archs']} == {
+        'sm_80': 1, 'sm_90': 1}
+    assert {x['v']: x['n'] for x in facets['dtypes']} == {
+        'bf16': 1, 'fp16': 1, 'fp32': 1, 'int8': 1}
+    assert {x['v']: x['n'] for x in facets['intrinsics']} == {
+        '__syncthreads': 1, 'avx2': 1, 'mma_sync': 1, 'tl.dot': 1}
+    assert {x['v']: x['n'] for x in facets['torch_ops']} == {
+        'attention': 1, 'conv2d': 1, 'matmul': 1}
+    assert facets['has_build_dir'] == [
+        {'v': True, 'n': 2}, {'v': False, 'n': 1}]
+
+
+def test_kernel_structured_page_uses_kernel_envelope_contract(tmp_path):
+    index = load_kernels(tmp_path)
+    where, args = index.adapter.build_where(SearchReq(filters={
+        'accelerators': ['nvidia'],
+    }))
+
+    total, cards = structured_page(
+        index.db(), index, index.adapter, where=where, args=args,
+        sort='downloads', page=0, page_size=24)
+
+    assert index.adapter.result_key == 'kernels'
+    assert total == 2
+    assert [card['repo_id'] for card in cards] == [
+        'alice/fused-gemm', 'bob/paged-attention']
+
+
+def test_kernel_query_text_is_preserved_for_semantic_search(tmp_path):
+    index = load_kernels(tmp_path)
+
+    assert index.adapter.extract_constraints(
+        SearchReq(query='  fused attention  ')) == 'fused attention'
+
+
+# ── ContainerAdapter: request, filtering, cards and facets ───────────────────
+
+def test_container_defaults_to_requested_recipe_filter(loaded_containers):
+    request = SearchReq(filters={'artifact_kinds': ['recipe']})
+    where, args = loaded_containers.adapter.build_where(request)
+    kinds = {
+        row[0] for row in loaded_containers.db().execute(
+            f'SELECT artifact_kind FROM containers WHERE {where}', args)
+    }
+
+    assert kinds == {'recipe'}
+
+
+def test_container_filters_are_anded_across_groups_and_ored_within_group(
+        loaded_containers):
+    request = SearchReq(filters={
+        'artifact_kinds': ['recipe'],
+        'python_versions': ['3.11', '3.12'],
+        'accelerators': ['nvidia', 'amd'],
+        'cuda_versions': ['12.8'],
+        'frameworks': ['pytorch'],
+        'has_multistage': True,
+    })
+    where, args = loaded_containers.adapter.build_where(request)
+    ids = [row[0] for row in loaded_containers.db().execute(
+        f'SELECT repo_id FROM containers WHERE {where}', args)]
+
+    assert ids == ['alice/cuda-recipe']
+
+
+def test_container_archive_rows_appear_when_artifact_kind_filter_is_absent(
+        loaded_containers):
+    request = SearchReq(filters={
+        'python_versions': ['3.11'],
+        'cuda_versions': ['12.8'],
+        'frameworks': ['pytorch'],
+    })
+    where, args = loaded_containers.adapter.build_where(request)
+    ids = [row[0] for row in loaded_containers.db().execute(
+        f'SELECT repo_id FROM containers WHERE {where} ORDER BY row', args)]
+
+    assert ids == ['alice/cuda-recipe', 'dana/archive-bundle']
+
+
+def test_container_scalar_boolean_and_json_filters_execute_against_sqlite(
+        loaded_containers):
+    request = SearchReq(filters={
+        'repo_types': ['dataset'],
+        'services': ['jupyter', 'postgres'],
+        'package_managers': ['apt'],
+        'ports': ['8888'],
+        'has_compose': True,
+        'has_devcontainer': True,
+    })
+    where, args = loaded_containers.adapter.build_where(request)
+    ids = [row[0] for row in loaded_containers.db().execute(
+        f'SELECT repo_id FROM containers WHERE {where}', args)]
+
+    assert ids == ['carol/compose-stack']
+
+
+def test_container_query_text_is_preserved_for_semantic_search(
+        loaded_containers):
+    assert loaded_containers.adapter.extract_constraints(
+        SearchReq(query='  python 3.11 cuda 12.8  ')
+    ) == 'python 3.11 cuda 12.8'
+
+
+def test_container_card_decodes_json_arrays_and_preserves_empty_arrays(
+        loaded_containers):
+    row = loaded_containers.db().execute(
+        f'SELECT {loaded_containers.adapter.card_columns} FROM containers '
+        'WHERE row = 1').fetchone()
+
+    card = loaded_containers.adapter.card(row, 0.87654)
+
+    assert card['repo_id'] == 'bob/rocm-recipe'
+    assert card['repo_type'] == 'space'
+    assert card['artifact_path'] == 'docker/Dockerfile'
+    assert card['artifact_kind'] == 'recipe'
+    assert card['tags'] == ['docker', 'rocm']
+    assert card['artifact_files'] == ['docker/Dockerfile']
+    assert card['qualification_reasons'] == ['dockerfile']
+    assert card['base_images'] == ['rocm/pytorch:latest']
+    assert card['accelerators'] == ['amd']
+    assert card['cuda_versions'] == []
+    assert card['rocm_versions'] == ['6.1']
+    assert card['python_versions'] == ['3.12']
+    assert card['node_versions'] == ['20']
+    assert card['operating_systems'] == ['ubuntu24.04']
+    assert card['ports'] == ['7860']
+    assert card['services'] == []
+    assert card['package_managers'] == ['apt', 'pip']
+    assert card['frameworks'] == ['pytorch']
+    assert card['entrypoints'] == []
+    assert card['commands'] == ['python launch.py']
+    assert card['has_compose'] is False
+    assert card['has_devcontainer'] is False
+    assert card['has_multistage'] is False
+    assert card['score'] == 0.8765
+    assert 'document' not in card
+
+
+def test_container_facets_count_scalars_arrays_and_booleans(
+        loaded_containers):
+    facets = loaded_containers.facets
+
+    assert facets['total'] == 4
+    assert {item['v']: item['n'] for item in facets['repo_types']} == {
+        'dataset': 2, 'model': 1, 'space': 1}
+    assert {item['v']: item['n'] for item in facets['artifact_kinds']} == {
+        'recipe': 3, 'archive': 1}
+    assert {item['v']: item['n'] for item in facets['base_images']} == {
+        'nvidia/cuda:12.8.0-runtime-ubuntu22.04': 1,
+        'rocm/pytorch:latest': 1,
+        'python:3.10-slim': 1,
+        'ubuntu:22.04': 1,
+    }
+    assert {item['v']: item['n'] for item in facets['accelerators']} == {
+        'nvidia': 2, 'amd': 1}
+    assert {item['v']: item['n'] for item in facets['python_versions']} == {
+        '3.11': 2, '3.12': 1, '3.10': 1}
+    assert {item['v']: item['n'] for item in facets['frameworks']} == {
+        'pytorch': 3, 'fastapi': 1}
+    assert {item['v']: item['n'] for item in facets['services']} == {
+        'api': 1, 'jupyter': 1, 'postgres': 1, 'worker': 1}
+    assert {item['v']: item['n'] for item in facets['ports']} == {
+        '7860': 2, '5432': 1, '8080': 1, '8888': 1}
+    assert facets['has_compose'] == [
+        {'v': True, 'n': 1}, {'v': False, 'n': 3}]
+    assert facets['has_devcontainer'] == [
+        {'v': True, 'n': 1}, {'v': False, 'n': 3}]
+    assert facets['has_multistage'] == [
+        {'v': True, 'n': 1}, {'v': False, 'n': 3}]