feat: tunable ranking, refresh status, chroma backup + admin endpoints

Three small improvements that move the operational baseline forward without changing the existing trust model. 1. Tunable retrieval ranking weights - rank_project_match_boost, rank_query_token_step, rank_query_token_cap, rank_path_high_signal_boost, rank_path_low_signal_penalty are now Settings fields - all overridable via ATOCORE_* env vars - retriever no longer hard-codes 2.0 / 1.18 / 0.72 / 0.08 / 1.32 - lets ranking be tuned per environment as Wave 1 is exercised without code changes 2. /projects/{name}/refresh status - refresh_registered_project now returns an overall status field ("ingested", "partial", "nothing_to_ingest") plus roots_ingested and roots_skipped counters - ProjectRefreshResponse advertises the new fields so callers can rely on them - covers the case where every configured root is missing on disk 3. Chroma cold snapshot + admin backup endpoints - create_runtime_backup now accepts include_chroma and writes a cold directory copy of the chroma persistence path - new list_runtime_backups() and validate_backup() helpers - new endpoints: - POST /admin/backup create snapshot (optional chroma) - GET /admin/backup list snapshots - GET /admin/backup/{stamp}/validate structural validation - chroma snapshots are taken under exclusive_ingestion() so a refresh or ingest cannot race with the cold copy - backup metadata records what was actually included and how big Tests: - 8 new tests covering tunable weights, refresh status branches (ingested / partial / nothing_to_ingest), chroma snapshot, list, validate, and the API endpoints (including the lock-acquisition path) - existing fake refresh stubs in test_api_storage.py updated for the expanded ProjectRefreshResponse model - full suite: 105 passing (was 97) next-steps doc updated to reflect that the chroma snapshot + restore validation gap from current-state.md is now closed in code; only the operational retention policy remains.
2026-04-06 18:42:19 -04:00
parent 14ab7c8e9f
commit c9b9eede25
10 changed files with 615 additions and 13 deletions
--- a/tests/test_api_storage.py
+++ b/tests/test_api_storage.py
@@ -129,6 +129,9 @@ def test_project_refresh_endpoint_uses_registered_roots(tmp_data_dir, monkeypatc
            "aliases": ["p05"],
            "description": "P05 docs",
            "purge_deleted": purge_deleted,
+            "status": "ingested",
+            "roots_ingested": 1,
+            "roots_skipped": 0,
            "roots": [
                {
                    "source": "vault",
@@ -173,6 +176,9 @@ def test_project_refresh_endpoint_serializes_ingestion(tmp_data_dir, monkeypatch
            "aliases": ["p05"],
            "description": "P05 docs",
            "purge_deleted": purge_deleted,
+            "status": "nothing_to_ingest",
+            "roots_ingested": 0,
+            "roots_skipped": 0,
            "roots": [],
        }

@@ -429,6 +435,125 @@ def test_project_update_endpoint_rejects_collisions(tmp_data_dir, monkeypatch):
    assert "collisions" in response.json()["detail"]


+def test_admin_backup_create_without_chroma(tmp_data_dir, monkeypatch):
+    config.settings = config.Settings()
+    captured = {}
+
+    def fake_create_runtime_backup(timestamp=None, include_chroma=False):
+        captured["include_chroma"] = include_chroma
+        return {
+            "created_at": "2026-04-06T23:00:00+00:00",
+            "backup_root": "/tmp/fake",
+            "db_snapshot_path": "/tmp/fake/db/atocore.db",
+            "db_size_bytes": 0,
+            "registry_snapshot_path": "",
+            "chroma_snapshot_path": "",
+            "chroma_snapshot_bytes": 0,
+            "chroma_snapshot_files": 0,
+            "chroma_snapshot_included": False,
+            "vector_store_note": "skipped",
+        }
+
+    monkeypatch.setattr("atocore.api.routes.create_runtime_backup", fake_create_runtime_backup)
+
+    client = TestClient(app)
+    response = client.post("/admin/backup", json={})
+
+    assert response.status_code == 200
+    assert captured == {"include_chroma": False}
+    body = response.json()
+    assert body["chroma_snapshot_included"] is False
+
+
+def test_admin_backup_create_with_chroma_holds_lock(tmp_data_dir, monkeypatch):
+    config.settings = config.Settings()
+    events = []
+
+    @contextmanager
+    def fake_lock():
+        events.append("enter")
+        try:
+            yield
+        finally:
+            events.append("exit")
+
+    def fake_create_runtime_backup(timestamp=None, include_chroma=False):
+        events.append(("backup", include_chroma))
+        return {
+            "created_at": "2026-04-06T23:30:00+00:00",
+            "backup_root": "/tmp/fake",
+            "db_snapshot_path": "/tmp/fake/db/atocore.db",
+            "db_size_bytes": 0,
+            "registry_snapshot_path": "",
+            "chroma_snapshot_path": "/tmp/fake/chroma",
+            "chroma_snapshot_bytes": 4,
+            "chroma_snapshot_files": 1,
+            "chroma_snapshot_included": True,
+            "vector_store_note": "included",
+        }
+
+    monkeypatch.setattr("atocore.api.routes.exclusive_ingestion", fake_lock)
+    monkeypatch.setattr("atocore.api.routes.create_runtime_backup", fake_create_runtime_backup)
+
+    client = TestClient(app)
+    response = client.post("/admin/backup", json={"include_chroma": True})
+
+    assert response.status_code == 200
+    assert events == ["enter", ("backup", True), "exit"]
+    assert response.json()["chroma_snapshot_included"] is True
+
+
+def test_admin_backup_list_and_validate_endpoints(tmp_data_dir, monkeypatch):
+    config.settings = config.Settings()
+
+    def fake_list_runtime_backups():
+        return [
+            {
+                "stamp": "20260406T220000Z",
+                "path": "/tmp/fake/snapshots/20260406T220000Z",
+                "has_metadata": True,
+                "metadata": {"db_snapshot_path": "/tmp/fake/snapshots/20260406T220000Z/db/atocore.db"},
+            }
+        ]
+
+    def fake_validate_backup(stamp):
+        if stamp == "missing":
+            return {
+                "stamp": stamp,
+                "path": f"/tmp/fake/snapshots/{stamp}",
+                "exists": False,
+                "errors": ["snapshot_directory_missing"],
+            }
+        return {
+            "stamp": stamp,
+            "path": f"/tmp/fake/snapshots/{stamp}",
+            "exists": True,
+            "db_ok": True,
+            "registry_ok": True,
+            "chroma_ok": None,
+            "valid": True,
+            "errors": [],
+        }
+
+    monkeypatch.setattr("atocore.api.routes.list_runtime_backups", fake_list_runtime_backups)
+    monkeypatch.setattr("atocore.api.routes.validate_backup", fake_validate_backup)
+
+    client = TestClient(app)
+
+    listing = client.get("/admin/backup")
+    assert listing.status_code == 200
+    listing_body = listing.json()
+    assert "backup_dir" in listing_body
+    assert listing_body["backups"][0]["stamp"] == "20260406T220000Z"
+
+    valid = client.get("/admin/backup/20260406T220000Z/validate")
+    assert valid.status_code == 200
+    assert valid.json()["valid"] is True
+
+    missing = client.get("/admin/backup/missing/validate")
+    assert missing.status_code == 404
+
+
 def test_query_endpoint_accepts_project_hint(monkeypatch):
    def fake_retrieve(prompt, top_k=10, filter_tags=None, project_hint=None):
        assert prompt == "architecture"