fix(api): persist scratch/local and bound heavy compute concurrency

Keep async job and chart-cache files across API recreates, freeze jyotish_api_server.py growth, and fail fast with 429 when rectification or high-rigor compute is saturated.

Co-authored-by: Cursor <cursoragent@cursor.com>

scripts/api_heavy_compute_gate.py

@@ -0,0 +1,116 @@
+"""Fail-fast bounded concurrency for heavy Jyotish API compute endpoints.
+
+Request threads that run rectification scans or high-rigor workflows share one
+process-wide semaphore sized for the 2 vCPU production host. Saturated requests
+return immediately; they are not queued. Health checks and other light routes
+must not call this gate.
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+
+DEFAULT_CONCURRENCY = 2
+DEFAULT_RETRY_AFTER_SECONDS = 2
+ENV_CONCURRENCY = "JYOTISH_HEAVY_COMPUTE_CONCURRENCY"
+ENV_RETRY_AFTER = "JYOTISH_HEAVY_COMPUTE_RETRY_AFTER_SECONDS"
+
+HEAVY_COMPUTE_PATHS = frozenset(
+    {
+        "/api/rectification/sensitivity_scan",
+        "/api/active_rectification_events",
+        "/api/active_rectification_events_v4",
+        "/api/rectification/v5/candidate-features",
+        "/api/rectification/v5/score",
+        "/api/rectification/v5/diagnostics",
+        "/api/rectification/v5/vedastro-validate",
+        "/api/dynamic_rectification_opportunities",
+        "/api/dynamic_rectification_score",
+        "/api/high_rigor_workflow",
+        "/api/consultation_workflow",
+        "/api/professional_reading",
+        "/api/vedastro/range_scan",
+        "/api/vedastro_gateway/run",
+        "/api/thematic_report",
+    }
+)
+
+_state_lock = threading.Lock()
+_semaphore: threading.BoundedSemaphore | None = None
+_retry_after_seconds = DEFAULT_RETRY_AFTER_SECONDS
+
+
+class HeavyComputeBusy(RuntimeError):
+    """No heavy-compute slot is free; callers must fail fast with HTTP 429."""
+
+    error_code = "ERR_COMPUTE_BUSY"
+
+    def __init__(self, retry_after_seconds: int) -> None:
+        super().__init__(
+            "Heavy compute capacity is saturated; retry after the Retry-After delay."
+        )
+        self.retry_after_seconds = max(int(retry_after_seconds), 1)
+
+
+def _parse_positive_int(raw: str | None, default: int) -> int:
+    try:
+        value = int(str(raw or "").strip())
+    except (TypeError, ValueError):
+        return default
+    return value if value >= 1 else default
+
+
+def is_heavy_compute_path(path: str) -> bool:
+    if path in HEAVY_COMPUTE_PATHS:
+        return True
+    return path.startswith("/api/vedastro_gateway/jobs/") and path.endswith("/run")
+
+
+def reset_heavy_compute_gate(
+    *,
+    limit: int | None = None,
+    retry_after_seconds: int | None = None,
+) -> None:
+    """Rebuild the process-wide semaphore. Tests must call this after env changes."""
+    global _semaphore, _retry_after_seconds
+    resolved_limit = (
+        limit
+        if limit is not None
+        else _parse_positive_int(os.environ.get(ENV_CONCURRENCY), DEFAULT_CONCURRENCY)
+    )
+    resolved_retry = (
+        retry_after_seconds
+        if retry_after_seconds is not None
+        else _parse_positive_int(os.environ.get(ENV_RETRY_AFTER), DEFAULT_RETRY_AFTER_SECONDS)
+    )
+    with _state_lock:
+        _retry_after_seconds = resolved_retry
+        _semaphore = threading.BoundedSemaphore(resolved_limit)
+
+
+def _ensure_locked() -> tuple[threading.BoundedSemaphore, int]:
+    global _semaphore, _retry_after_seconds
+    if _semaphore is None:
+        limit = _parse_positive_int(os.environ.get(ENV_CONCURRENCY), DEFAULT_CONCURRENCY)
+        _retry_after_seconds = _parse_positive_int(
+            os.environ.get(ENV_RETRY_AFTER), DEFAULT_RETRY_AFTER_SECONDS
+        )
+        _semaphore = threading.BoundedSemaphore(limit)
+    return _semaphore, _retry_after_seconds
+
+
+def acquire_heavy_compute_slot(path: str) -> threading.BoundedSemaphore | None:
+    """Acquire a slot for a gated path. Light paths return None. Fail-fast on saturation."""
+    if not is_heavy_compute_path(path):
+        return None
+    with _state_lock:
+        semaphore, retry_after = _ensure_locked()
+    if not semaphore.acquire(blocking=False):
+        raise HeavyComputeBusy(retry_after)
+    return semaphore
+
+
+def release_heavy_compute_slot(slot: threading.BoundedSemaphore | None) -> None:
+    if slot is not None:
+        slot.release()

scripts/jyotish_api_server.py

@@ -93,6 +93,18 @@ except ModuleNotFoundError:  # pragma: no cover - script execution path
     from western_oracle_adapter import build_packet_from_oracle_payload
     from western_chart_engine import build_tropical_western_evidence_packet
     from western_timing_engine import build_timing_techniques
+try:
+    from scripts.api_heavy_compute_gate import (
+        HeavyComputeBusy,
+        acquire_heavy_compute_slot,
+        release_heavy_compute_slot,
+    )
+except ModuleNotFoundError:  # pragma: no cover - script execution path
+    from api_heavy_compute_gate import (
+        HeavyComputeBusy,
+        acquire_heavy_compute_slot,
+        release_heavy_compute_slot,
+    )
 
 from ayanamsa_utils import DEFAULT_AYANAMSA_NAME, UnsupportedAyanamsaError, normalize_ayanamsa_name
 from raman_support_observations import build_raman_support_observations
@@ -3137,7 +3149,7 @@ class RateLimited(RuntimeError):
 class JyotishAPIHandler(BaseHTTPRequestHandler):
     server_version = 'JyotishAPI/6.9.14'
 
-    def _json(self, data, status=200):
+    def _json(self, data, status=200, extra_headers=None):
         self.send_response(status)
         self.send_header('Content-Type', 'application/json; charset=utf-8')
         self._send_cors_headers()
@@ -3145,11 +3157,13 @@ class JyotishAPIHandler(BaseHTTPRequestHandler):
         self.send_header('Access-Control-Allow-Methods', 'GET, POST, OPTIONS')
         self.send_header('Access-Control-Allow-Headers', 'Content-Type, Authorization')
         self.send_header('Vary', 'Origin')
+        for key, value in (extra_headers or {}).items():
+            self.send_header(key, value)
         self.end_headers()
         self.wfile.write(json.dumps(data, ensure_ascii=False, default=str).encode())
 
-    def _error_json(self, message, status=500, error_code='ERR_INTERNAL'):
-        self._json({'success': False, 'error': message, 'error_code': error_code}, status)
+    def _error_json(self, message, status=500, error_code='ERR_INTERNAL', extra_headers=None):
+        self._json({'success': False, 'error': message, 'error_code': error_code}, status, extra_headers=extra_headers)
 
     def _html(self, content, status=200):
         encoded = content.encode('utf-8')
@@ -3364,9 +3378,11 @@ class JyotishAPIHandler(BaseHTTPRequestHandler):
 
     def do_POST(self):
         path = urlparse(self.path).path
+        compute_slot = None
         try:
             self._enforce_request_security(require_json=True)
             body = self._read_json_body()
+            compute_slot = acquire_heavy_compute_slot(path)
             if path == '/api/location/resolve':
                 city = str(body.get('city') or '').strip()
                 city_aliases = {'beijing': '北京', 'shanghai': '上海', 'guangzhou': '广州', 'shenzhen': '深圳'}
@@ -3567,6 +3583,13 @@ class JyotishAPIHandler(BaseHTTPRequestHandler):
                 self._json(result)
             else:
                 self._error_json(f'Unknown endpoint: {path}', 404, 'ERR_NOT_FOUND')
+        except HeavyComputeBusy as exc:
+            self._error_json(
+                str(exc),
+                429,
+                exc.error_code,
+                extra_headers={'Retry-After': str(exc.retry_after_seconds)},
+            )
         except RateLimited as exc:
             self._error_json(str(exc), 429, 'ERR_RATE_LIMITED')
         except BadRequest as e:
@@ -3581,6 +3604,8 @@ class JyotishAPIHandler(BaseHTTPRequestHandler):
             import logging
             logging.exception("[api_server] request failed for %s", path)
             self._error_json('Internal server error', 500, 'ERR_INTERNAL')
+        finally:
+            release_heavy_compute_slot(compute_slot)
 
     def _read_json_body(self):
         raw_length = self.headers.get('Content-Length', '0')

scripts/run_quality_gate.py

@@ -72,6 +72,10 @@ CORE_PYTEST_TARGETS = [
     "tests/test_session_management_entrypoints.py",
     # Pure source/SQL regex for the birth-time journey; no runtime services.
     "tests/test_birth_time_journey_contract.py",
+    # Freeze scripts/jyotish_api_server.py growth; new features must be modules.
+    "tests/test_api_server_growth_contract.py",
+    # Fail-fast heavy-compute concurrency gate (429 + Retry-After, health ungated).
+    "tests/test_api_heavy_compute_gate.py",
 ]
 
 RUNTIME_TRUTH_PYTEST_TARGETS = [