chore(sync): mirror backend .py + Dockerfile to Space (hf-sync-backend)

Automated backend sync from szl-holdings/a11oy main via hf-sync-backend.
Updated (differed from the Space): serve.py, szl_energy_operator.py
Deleted (gone from the repo + Dockerfile COPY set): (none)

Keeps the Space-built backend (serve.py + the Dockerfile-COPY'd .py
modules) identical to GitHub main so the Space never rebuilds from a
stale backend, new endpoints don't 404 there, and orphaned modules
removed from the repo don't linger in the Space tree.

serve.py

@@ -4930,26 +4930,39 @@ async def preflight_status() -> JSONResponse:
 
 @app.get("/api/a11oy/readyz")
 async def readyz() -> JSONResponse:
-    # Doctrine v11: /readyz now reflects the energy operator loop. The exact
-    # redeploy-stall we hit was: the service restarts, the GPU lungs stay reachable,
-    # but the operator loop comes up STOPPED so joules freeze. Surface that as NOT
-    # ready (503) so an orchestrator/healthcheck catches it. If a lung is reachable
-    # AND the loop runs → ready (200). If NO lung is reachable → ready (200, honestly
-    # idle: there is nothing to compute against, not a fault — we never fake running).
-    operator = {"ready": True, "reason": "operator_check_unavailable"}
+    # Keep service readiness separate from optional capability readiness. A public
+    # CPU-only surface may serve in a truthful degraded state, while a deployment
+    # that declares the operator required must fail closed. A reachable lung with
+    # a stopped loop remains a hard 503 redeploy-stall signal.
+    required = (os.environ.get("A11OY_ENERGY_OPERATOR_REQUIRED", "0").strip().lower()
+                not in ("0", "false", "no", "off", ""))
+    operator = {
+        "service": "energy-operator",
+        "ready": False,
+        "service_ready": not required,
+        "required": required,
+        "state": "unknown",
+        "reason": "operator_check_unavailable",
+    }
     try:
         import szl_energy_operator as _szl_eo_ready
         operator = _szl_eo_ready.readiness()
-    except Exception as _eo_ready_e:  # pragma: no cover — never block readyz on import
-        operator = {"ready": True, "reason": f"operator_check_error:{type(_eo_ready_e).__name__}"}
-    ready = bool(operator.get("ready", True))
+    except Exception as _eo_ready_e:  # pragma: no cover — fail closed when required
+        operator["reason"] = f"operator_check_error:{type(_eo_ready_e).__name__}"
+    service_ready = bool(operator.get("service_ready", False))
+    capability_ready = bool(operator.get("ready", False))
+    status = (
+        "ready" if service_ready and capability_ready
+        else "ready_degraded" if service_ready
+        else "not_ready"
+    )
     return JSONResponse(
         {
-            "status": "ready" if ready else "not_ready",
+            "status": status,
             "backend": "local+proxy",
             "operator": operator,
         },
-        status_code=200 if ready else 503,
+        status_code=200 if service_ready else 503,
     )
 
 

szl_energy_operator.py

@@ -1524,6 +1524,7 @@ def handle_status() -> dict:
 # Env flag gating the boot auto-start. Defaults ON ("1"). Set to "0"/"false" to
 # disable (e.g. a box that should stay idle until a manual press-play).
 A11OY_ENERGY_AUTOSTART_ENV = "A11OY_ENERGY_AUTOSTART"
+A11OY_ENERGY_OPERATOR_REQUIRED_ENV = "A11OY_ENERGY_OPERATOR_REQUIRED"
 
 
 def autostart_enabled() -> bool:
@@ -1532,6 +1533,12 @@ def autostart_enabled() -> bool:
             not in ("0", "false", "no", "off", ""))
 
 
+def operator_required() -> bool:
+    """Return whether deployment readiness requires this capability."""
+    return (os.environ.get(A11OY_ENERGY_OPERATOR_REQUIRED_ENV, "0").strip().lower()
+            not in ("0", "false", "no", "off", ""))
+
+
 def autostart_if_lung_reachable() -> dict:
     """Boot hook: auto-press-play the operator loop, but ONLY when honest to do so.
 
@@ -1559,23 +1566,41 @@ def autostart_if_lung_reachable() -> dict:
 
 
 def readiness() -> dict:
-    """Operator readiness for /readyz (Doctrine v11 — the exact redeploy-stall guard).
+    """Return separate capability and deployment-readiness truth.
 
-    UNHEALTHY (ready=False) iff a lung IS reachable but the loop is STOPPED — the
-    precise state hit on every box redeploy (lungs up, loop never auto-started, so
-    joules freeze). Otherwise ready=True: either the loop is running, or no lung is
-    reachable (honestly idle — nothing to compute against, not a fault)."""
+    ``ready`` describes the operator capability and is true only when the loop
+    runs. ``service_ready`` controls the host readiness contract: an explicitly
+    optional, unreachable operator degrades the host without removing it from
+    service. A reachable-but-stopped loop always fails readiness because that is
+    the redeploy-stall failure this guard exists to catch.
+    """
     op = get_operator()
     running = op.is_running()
     lung = op.any_lung_reachable()
-    ready = running or not lung
+    required = operator_required()
+    if running:
+        state = "ready"
+        reason = "ok"
+        service_ready = True
+    elif lung:
+        state = "stopped"
+        reason = "operator_stopped_while_lung_reachable"
+        service_ready = False
+    else:
+        state = "unavailable"
+        reason = ("required_lung_unreachable" if required
+                  else "optional_lung_unreachable")
+        service_ready = not required
     return {
         "service": "energy-operator",
-        "ready": ready,
+        "ready": running,
+        "service_ready": service_ready,
+        "required": required,
+        "state": state,
         "operator_running": running,
         "lung_reachable": lung,
         "autostart_enabled": autostart_enabled(),
-        "reason": ("ok" if ready else "operator_stopped_while_lung_reachable"),
+        "reason": reason,
     }