Upload 4 files

README.md

@@ -133,15 +133,16 @@ See `CHANGELOG_V194.md` for the Model Pre-scan Decision Card UI pass.
 See `CHANGELOG_V195.md` for the Runtime CSS Cleanup with Legacy Safety Net pass.
 
 
-Current release: Agentic Space Factory v198.26.119.
+Current release: Agentic Space Factory v198.26.121.
 
-## v198.26.119 — Run Stats Badge Reconciliation
+## v198.26.121 — Target Space Identity Override
 
-- Aligns the compact Run Stats badge with the detailed Build Status card.
-- Shows `running` in the compact badge only for active Build Runs, not stale/non-terminal linked validation summaries.
-- Keeps linked Space Test counts visible while leaving linked-test lifecycle detail in the dedicated stats band.
+- Adds an auditable Target Space override for Build Runs whose generated Space was renamed manually in Hugging Face settings.
+- Preserves the original generated target Space while using the effective override for future Space Tests and quick links.
+- Keeps validation linked to the selected Build Run: arbitrary target edits are still rejected unless the override was explicitly saved first.
+- Excludes `TARGET_SPACE_OVERRIDE.json` from target Space release payloads while preserving it in the run bucket.
 
-See `CHANGELOG_V198_26_119.md`.
+See `CHANGELOG_V198_26_121.md`.
 
 ## v198.26.118 — Runtime Risk Hints Advisory Layer
 

app.py

@@ -11,7 +11,13 @@ from fastapi import FastAPI, HTTPException, Request
 from fastapi.responses import HTMLResponse, JSONResponse, FileResponse, RedirectResponse
 from huggingface_hub import HfApi, attach_huggingface_oauth
 
-from src.bucket import RunPaths, check_user_bucket, create_user_bucket, delete_run_folder, read_run_bundle, list_recent_runs, read_json, upsert_run_index_entry, write_json, write_launch_metadata
+from src.bucket import RunPaths, append_run_event, check_user_bucket, create_user_bucket, delete_run_folder, read_run_bundle, list_recent_runs, read_json, upsert_run_index_entry, write_json, write_launch_metadata
+from src.target_space_identity import (
+    TARGET_SPACE_OVERRIDE_FILENAME,
+    normalize_target_space_id as normalize_effective_target_space_id,
+    target_space_identity_overlay,
+    target_space_url as effective_target_space_url,
+)
 from src.config import settings, user_bucket_source
 from src.eval_config import activate_eval_archive_config, disable_eval_archive_config, flush_eval_archive_records, public_eval_config
 from src.eval_archive import maybe_publish_eval_record
@@ -328,10 +334,10 @@ def _target_space_from_events(events: list[dict[str, Any]] | None, *, require_su
 def _resolve_target_space_identity(run_id: str | None, bundle: dict[str, Any], *, bucket_source: str | None, job_url: str | None = None) -> dict[str, Any]:
     """Return canonical Space links from all stable run sources.
 
-    v198.26.4: buttons stayed disabled when summary.target_space_url was empty
-    even though create_space/upload_files had succeeded.  Resolve links from
-    summary/state/launch/runtime_upload_epoch/hardware events and expose a
-    single contract to the UI.
+    v198.26.121: apply an auditable Target Space identity override before
+    building UI links or validation prefill. The raw/generated target remains
+    available as target_space_original for audit; target_space is the effective
+    repo id to use for future validations and buttons.
     """
     summary = bundle.get("summary") or bundle.get("summary_file") or {}
     state = bundle.get("state") or {}
@@ -340,7 +346,7 @@ def _resolve_target_space_identity(run_id: str | None, bundle: dict[str, Any], *
     explicit_url = _first_non_empty(
         summary.get("target_space_url"), state.get("target_space_url"), launch.get("target_space_url")
     )
-    target = _normalize_target_space_id(
+    raw_target = _normalize_target_space_id(
         _first_non_empty(
             summary.get("target_space"), summary.get("target_space_id"),
             state.get("target_space"), state.get("target_space_id"),
@@ -349,21 +355,20 @@ def _resolve_target_space_identity(run_id: str | None, bundle: dict[str, Any], *
             _target_space_from_events(bundle.get("events") or []),
         )
     )
-    if explicit_url and not target:
-        target = _normalize_target_space_id(explicit_url)
-    target_space_url = explicit_url or (f"https://huggingface.co/spaces/{target}" if target else "")
+    if explicit_url and not raw_target:
+        raw_target = _normalize_target_space_id(explicit_url)
+    overlay = target_space_identity_overlay({**bundle, "summary": summary, "state": state, "launch": launch})
+    target = overlay.get("target_space") or raw_target
+    target_space_url = overlay.get("target_space_url") or (f"https://huggingface.co/spaces/{target}" if target else "")
     target_space_settings_url = f"{target_space_url}/settings" if target_space_url else ""
     events = bundle.get("events") or []
     space_runtime = bundle.get("space_runtime") or {}
     runtime_history = runtime_upload_epoch.get("history") if isinstance(runtime_upload_epoch.get("history"), list) else []
-    create_event_ok = bool(target and any(str((e or {}).get("step") or "") in {"create_space", "create_space_hardware"} and str((e or {}).get("status") or "").lower() == "success" for e in events if isinstance(e, dict)))
+    create_event_ok = bool(raw_target and any(str((e or {}).get("step") or "") in {"create_space", "create_space_hardware"} and str((e or {}).get("status") or "").lower() == "success" for e in events if isinstance(e, dict)))
     upload_event_ok = bool(any(str((e or {}).get("step") or "") in {"upload_files", "runtime_upload_epoch"} and str((e or {}).get("status") or "").lower() == "success" for e in events if isinstance(e, dict)))
     runtime_uploaded = bool(runtime_upload_epoch.get("last_upload_completed_at") or runtime_upload_epoch.get("upload_sequence") or runtime_history or upload_event_ok)
     space_runtime_known = bool(isinstance(space_runtime, dict) and (space_runtime.get("stage") or space_runtime.get("status") or space_runtime.get("runtime_status") or space_runtime.get("updated_at") or space_runtime.get("url")))
-    # v198.26.9: Space links are durable run facts, not a projection of the
-    # latest 100 events.  A runtime upload epoch or a persisted runtime probe
-    # proves that the Space existed even if the final outcome later failed.
-    space_created = bool(target and (create_event_ok or runtime_uploaded or space_runtime_known))
+    space_created = bool(target and (create_event_ok or runtime_uploaded or space_runtime_known or overlay.get("target_space_override_active")))
     sources = []
     if create_event_ok:
         sources.append("create_space_event")
@@ -375,14 +380,21 @@ def _resolve_target_space_identity(run_id: str | None, bundle: dict[str, Any], *
         sources.append("space_runtime")
     if explicit_url:
         sources.append("explicit_target_space_url")
-    links_ready = bool(target_space_url and (space_created or runtime_uploaded or space_runtime_known))
+    if overlay.get("target_space_override_active"):
+        sources.insert(0, "target_space_override")
+    links_ready = bool(target_space_url and (space_created or runtime_uploaded or space_runtime_known or overlay.get("target_space_override_active")))
     return {
-        "schema_version": "space_identity.v198_26_9",
+        "schema_version": "space_identity.v198_26_121",
         "target_space": target,
         "target_space_id": target,
         "target_space_known": bool(target),
         "target_space_url": target_space_url,
         "target_space_settings_url": target_space_settings_url,
+        "target_space_original": overlay.get("target_space_original") or raw_target,
+        "target_space_original_url": overlay.get("target_space_original_url") or (f"https://huggingface.co/spaces/{raw_target}" if raw_target else ""),
+        "target_space_override_active": bool(overlay.get("target_space_override_active")),
+        "target_space_override": overlay.get("target_space_override") or {},
+        "target_space_source": overlay.get("target_space_source") or "generated_run",
         "space_created": bool(space_created),
         "runtime_uploaded": bool(runtime_uploaded),
         "space_uploaded": bool(runtime_uploaded),
@@ -406,6 +418,131 @@ def _api_links(*, run_id: str | None, bucket_source: str | None, target_space: s
     }
 
 
+
+
+def _run_target_override_path(run_id: str, bucket_source: str) -> str:
+    return f"{RunPaths(run_id, bucket_source=bucket_source).root}/{TARGET_SPACE_OVERRIDE_FILENAME}"
+
+
+def _target_space_override_response(run_id: str, bucket_source: str, bundle: dict[str, Any]) -> dict[str, Any]:
+    identity = _resolve_target_space_identity(run_id, bundle, bucket_source=bucket_source, job_url=(bundle.get("state") or {}).get("job_url") or (bundle.get("summary") or {}).get("job_url") or "")
+    return {
+        "run_id": run_id,
+        "bucket_source": bucket_source,
+        "target_space": identity.get("target_space") or "",
+        "target_space_id": identity.get("target_space") or "",
+        "target_space_url": identity.get("target_space_url") or "",
+        "target_space_settings_url": identity.get("target_space_settings_url") or "",
+        "target_space_original": identity.get("target_space_original") or "",
+        "target_space_original_url": identity.get("target_space_original_url") or "",
+        "target_space_override_active": bool(identity.get("target_space_override_active")),
+        "target_space_override": identity.get("target_space_override") or {},
+        "target_space_source": identity.get("target_space_source") or "generated_run",
+        "space_identity": identity,
+        "links": {**identity, "run_id": run_id, "bucket_source": bucket_source},
+    }
+
+
+def _assert_override_repo_allowed(*, target_space: str, username: str, token: str | None) -> None:
+    owner = target_space.split("/", 1)[0] if "/" in target_space else ""
+    if username and owner and owner != username:
+        raise ValueError(f"Target Space override must stay in your namespace for now ({username}/...).")
+    try:
+        HfApi(token=token).repo_info(repo_id=target_space, repo_type="space", token=token)
+    except Exception as exc:  # noqa: BLE001
+        raise ValueError(f"Could not verify target Space `{target_space}`. Make sure it exists and your OAuth token can access it. {redact(str(exc))}") from exc
+
+
+def _write_target_space_override(
+    *,
+    run_id: str,
+    bucket_source: str,
+    username: str,
+    token: str | None,
+    target_space: str,
+    reason: str,
+) -> dict[str, Any]:
+    bundle = read_run_bundle(run_id, bucket_source=bucket_source, token=token, include_heavy=False)
+    if _run_is_validation_like({"run_id": run_id, **bundle}):
+        raise ValueError("Target Space override can only be set on a Build Run, not on a validation run.")
+    original_identity = target_space_identity_overlay(bundle)
+    original = original_identity.get("target_space_original") or original_identity.get("target_space") or ""
+    payload = {
+        "schema_version": "target_space_override.v1",
+        "status": "active",
+        "parent_build_run_id": run_id,
+        "original_target_space_id": original,
+        "target_space_id": target_space,
+        "target_space": target_space,
+        "target_space_url": effective_target_space_url(target_space),
+        "target_space_settings_url": f"{effective_target_space_url(target_space)}/settings",
+        "reason": reason,
+        "set_by": username,
+        "verified_repo_exists": True,
+        "updated_at": utc_now_iso(),
+    }
+    write_json(_run_target_override_path(run_id, bucket_source), payload, token=token)
+    try:
+        append_run_event(
+            run_id,
+            bucket_source=bucket_source,
+            step="target_space_override",
+            status="success",
+            message="Target Space identity override saved",
+            details={"target_space": target_space, "original_target_space": original, "reason": reason},
+            token=token,
+        )
+    except Exception:
+        pass
+    refreshed = read_run_bundle(run_id, bucket_source=bucket_source, token=token, include_heavy=False)
+    response = _target_space_override_response(run_id, bucket_source, refreshed)
+    try:
+        summary = refreshed.get("summary") or {}
+        upsert_run_index_entry(run_id, bucket_source=bucket_source, summary={**summary, **response, "updated_at": utc_now_iso()}, token=token)
+    except Exception:
+        pass
+    return response
+
+
+def _clear_target_space_override(*, run_id: str, bucket_source: str, username: str, token: str | None, reason: str = "") -> dict[str, Any]:
+    bundle = read_run_bundle(run_id, bucket_source=bucket_source, token=token, include_heavy=False)
+    if _run_is_validation_like({"run_id": run_id, **bundle}):
+        raise ValueError("Target Space override can only be cleared on a Build Run, not on a validation run.")
+    current = bundle.get("target_space_override") or {}
+    original_identity = target_space_identity_overlay(bundle)
+    payload = {
+        "schema_version": "target_space_override.v1",
+        "status": "cleared",
+        "parent_build_run_id": run_id,
+        "previous_target_space_id": current.get("target_space_id") or current.get("target_space") or "",
+        "original_target_space_id": original_identity.get("target_space_original") or "",
+        "reason": reason or "Target Space override cleared by user.",
+        "cleared_by": username,
+        "updated_at": utc_now_iso(),
+    }
+    write_json(_run_target_override_path(run_id, bucket_source), payload, token=token)
+    try:
+        append_run_event(
+            run_id,
+            bucket_source=bucket_source,
+            step="target_space_override",
+            status="cleared",
+            message="Target Space identity override cleared",
+            details={"previous_target_space": payload["previous_target_space_id"], "reason": payload["reason"]},
+            token=token,
+        )
+    except Exception:
+        pass
+    refreshed = read_run_bundle(run_id, bucket_source=bucket_source, token=token, include_heavy=False)
+    response = _target_space_override_response(run_id, bucket_source, refreshed)
+    try:
+        summary = refreshed.get("summary") or {}
+        upsert_run_index_entry(run_id, bucket_source=bucket_source, summary={**summary, **response, "updated_at": utc_now_iso()}, token=token)
+    except Exception:
+        pass
+    return response
+
+
 def _job_id_from_run_bundle(summary: dict[str, Any], launch: dict[str, Any], state: dict[str, Any]) -> str:
     return str(summary.get("job_id") or launch.get("job_id") or state.get("job_id") or "").strip()
 
@@ -600,13 +737,17 @@ def _build_live_run_snapshot(
     view_bundle["eval_publish_status"] = eval_publish
     space_identity = _resolve_target_space_identity(run_id, view_bundle, bucket_source=bucket_source, job_url=effective_state.get("job_url") or effective_summary.get("job_url"))
     if space_identity.get("target_space"):
-        effective_state.setdefault("target_space", space_identity["target_space"])
-        effective_state.setdefault("target_space_id", space_identity["target_space"])
-        effective_summary.setdefault("target_space", space_identity["target_space"])
-        effective_summary.setdefault("target_space_id", space_identity["target_space"])
+        effective_state["target_space"] = space_identity["target_space"]
+        effective_state["target_space_id"] = space_identity["target_space"]
+        effective_state["target_space_original"] = space_identity.get("target_space_original") or effective_state.get("target_space_original") or ""
+        effective_state["target_space_override_active"] = bool(space_identity.get("target_space_override_active"))
+        effective_summary["target_space"] = space_identity["target_space"]
+        effective_summary["target_space_id"] = space_identity["target_space"]
+        effective_summary["target_space_original"] = space_identity.get("target_space_original") or effective_summary.get("target_space_original") or ""
+        effective_summary["target_space_override_active"] = bool(space_identity.get("target_space_override_active"))
     if space_identity.get("target_space_url"):
-        effective_state.setdefault("target_space_url", space_identity["target_space_url"])
-        effective_summary.setdefault("target_space_url", space_identity["target_space_url"])
+        effective_state["target_space_url"] = space_identity["target_space_url"]
+        effective_summary["target_space_url"] = space_identity["target_space_url"]
     view_bundle["state"] = effective_state
     view_bundle["summary"] = effective_summary
     view_bundle["space_identity"] = space_identity
@@ -1036,17 +1177,26 @@ def register_custom_routes(fastapi_app: FastAPI) -> None:
             parent_bundle = read_run_bundle(parent_build_run_id, bucket_source=bucket_status.get("bucket_source") or user_bucket_source(username=ctx["username"], bucket_name=bucket_name), token=ctx["token"], include_heavy=True)
             if _run_is_validation_like({"run_id": parent_build_run_id, **parent_bundle}):
                 raise ValueError("Space Test must be linked to a Build Run, not to another validation run. Select the parent Build Run and retry validation.")
-            parent_summary = parent_bundle.get("summary") or {}
-            parent_target = parent_summary.get("target_space") or (parent_bundle.get("state") or {}).get("target_space") or (parent_bundle.get("launch") or {}).get("target_space") or ""
-            requested_target = str(payload.get("target_space_id") or "").strip()
+            parent_identity = _resolve_target_space_identity(
+                parent_build_run_id,
+                parent_bundle,
+                bucket_source=bucket_status.get("bucket_source") or user_bucket_source(username=ctx["username"], bucket_name=bucket_name),
+                job_url=(parent_bundle.get("state") or {}).get("job_url") or (parent_bundle.get("summary") or {}).get("job_url"),
+            )
+            parent_target = parent_identity.get("target_space") or ""
+            requested_target = normalize_effective_target_space_id(payload.get("target_space_id") or "")
             if not parent_target:
                 raise ValueError("Linked Space Test requires a parent Build Run with a generated target Space.")
             if requested_target != parent_target:
-                raise ValueError("Space Test must remain linked to the selected Build Run target Space. Standalone validation is not supported in this app.")
+                raise ValueError("Space Test must remain linked to the selected Build Run effective target Space. Save a Target Space override first if the Space was renamed.")
             parent_view = build_run_view_model(parent_build_run_id, parent_bundle, bucket_source=bucket_status.get("bucket_source") or user_bucket_source(username=ctx["username"], bucket_name=bucket_name))
             space_test_policy = parent_view.get("space_test_policy") or parent_view.get("space_test", {}).get("policy") or {}
             if not space_test_policy.get("enabled"):
                 raise ValueError(str(space_test_policy.get("message") or "This Build Run is not eligible for linked Space Test yet."))
+            expert_intervention_required = bool(payload.get("expert_intervention_required"))
+            expert_intervention_note = str(payload.get("expert_intervention_note") or "").strip()
+            if expert_intervention_required and not expert_intervention_note:
+                raise ValueError("Expert intervention acceptance requires a short note describing the manual repair before validation.")
             payload_source_raw = str(payload.get("payload_source") or "").strip()
             manual_endpoint_override = bool(payload.get("endpoint_override")) or payload_source_raw == "endpoint_registry_manual_override"
             api_name_for_validation = str(payload.get("api_name") or "").strip()
@@ -1070,6 +1220,9 @@ def register_custom_routes(fastapi_app: FastAPI) -> None:
                 api_name_for_validation = ""
             requested_validation_mode = space_test_policy.get("mode") or payload.get("validation_mode") or "complete"
             validation_mode_for_launch = "complete" if manual_endpoint_override and str(requested_validation_mode or "").strip().lower() == "replay" else requested_validation_mode
+            base_validation_mode_for_launch = validation_mode_for_launch
+            if expert_intervention_required:
+                validation_mode_for_launch = "expert_acceptance"
             # Compatibility anchor: "ui_payload_source": payload.get("payload_source") or ""
             validation_launch_payload = {
                 "schema_version": "1.0",
@@ -1081,6 +1234,10 @@ def register_custom_routes(fastapi_app: FastAPI) -> None:
                 "test_args": test_args,
                 "test_kwargs": test_kwargs,
                 "validation_mode": validation_mode_for_launch,
+                "base_validation_mode": base_validation_mode_for_launch,
+                "expert_intervention_required": expert_intervention_required,
+                "expert_intervention_note": expert_intervention_note,
+                "expert_acceptance_requires_validation": bool(expert_intervention_required),
                 "payload_source": (payload.get("payload_source") if manual_endpoint_override else "parent_automatic_smoke") if replay_source else (payload.get("payload_source") or "ui_payload"),
                 "endpoint_override": bool(manual_endpoint_override),
                 "endpoint_registry_source_run_id": payload.get("endpoint_registry_source_run_id") or "",
@@ -1089,6 +1246,7 @@ def register_custom_routes(fastapi_app: FastAPI) -> None:
                 "space_test_policy": {
                     "mode": space_test_policy.get("mode"),
                     "launch_mode": validation_mode_for_launch,
+                    "base_launch_mode": base_validation_mode_for_launch,
                     "requires_endpoint_discovery": bool(space_test_policy.get("requires_endpoint_discovery")),
                     "effective_status_on_success": space_test_policy.get("effective_status_on_success"),
                 },
@@ -1104,7 +1262,9 @@ def register_custom_routes(fastapi_app: FastAPI) -> None:
                 expected_output_type=validation_launch_payload["expected_output_type"],
                 live_timeout_seconds=payload.get("live_timeout_seconds") or 1800,
                 validation_mode=validation_launch_payload["validation_mode"],  # effectively: validation_mode=space_test_policy.get("mode")
-                effective_status_on_success=space_test_policy.get("effective_status_on_success") or "validated_after_manual_space_test",
+                effective_status_on_success="success_with_expert_intervention" if expert_intervention_required else (space_test_policy.get("effective_status_on_success") or "validated_after_manual_space_test"),
+                expert_intervention_required=expert_intervention_required,
+                expert_intervention_note=expert_intervention_note,
                 parent_replay_source_json=json.dumps(replay_source, ensure_ascii=False) if replay_source and not manual_endpoint_override else None,
                 validation_launch_payload_json=json.dumps(validation_launch_payload, ensure_ascii=False),
                 run_id=payload.get("run_id"),
@@ -1133,6 +1293,51 @@ def register_custom_routes(fastapi_app: FastAPI) -> None:
             pass
         return JSONResponse(result)
 
+    @fastapi_app.post("/api/runs/{run_id}/target-space-override")
+    async def api_set_target_space_override(request: Request, run_id: str, payload: dict[str, Any]):  # type: ignore[no-untyped-def]
+        ctx = _oauth_context_from_request(request)
+        bucket_name = payload.get("bucket_name") or settings.bucket_name
+        bucket_source = user_bucket_source(username=ctx["username"], bucket_name=bucket_name)
+        run_id = validate_run_id(run_id)
+        target = normalize_effective_target_space_id(payload.get("target_space_id") or payload.get("target_space") or "")
+        if not target:
+            raise HTTPException(status_code=400, detail="Enter a valid Hugging Face Space repo ID like owner/space-name.")
+        reason = str(payload.get("reason") or "").strip()
+        if not reason:
+            raise HTTPException(status_code=400, detail="Target Space override requires a short reason, for example: renamed manually in HF Space settings.")
+        try:
+            _assert_override_repo_allowed(target_space=target, username=ctx["username"], token=ctx["token"])
+            result = _write_target_space_override(
+                run_id=run_id,
+                bucket_source=bucket_source,
+                username=ctx["username"],
+                token=ctx["token"],
+                target_space=target,
+                reason=reason,
+            )
+            return JSONResponse(result)
+        except Exception as exc:  # noqa: BLE001
+            raise _json_error(exc) from exc
+
+    @fastapi_app.post("/api/runs/{run_id}/target-space-override/clear")
+    async def api_clear_target_space_override(request: Request, run_id: str, payload: dict[str, Any] | None = None):  # type: ignore[no-untyped-def]
+        ctx = _oauth_context_from_request(request)
+        payload = payload or {}
+        bucket_name = payload.get("bucket_name") or settings.bucket_name
+        bucket_source = user_bucket_source(username=ctx["username"], bucket_name=bucket_name)
+        run_id = validate_run_id(run_id)
+        try:
+            result = _clear_target_space_override(
+                run_id=run_id,
+                bucket_source=bucket_source,
+                username=ctx["username"],
+                token=ctx["token"],
+                reason=str(payload.get("reason") or "").strip(),
+            )
+            return JSONResponse(result)
+        except Exception as exc:  # noqa: BLE001
+            raise _json_error(exc) from exc
+
     @fastapi_app.post("/api/progress/from-events")
     async def api_progress_from_events(payload: dict[str, Any]):  # type: ignore[no-untyped-def]
         events = payload.get("events") or []