MetaList 0.3.6__tar.gz → 0.3.8__tar.gz

{metalist-0.3.6 → metalist-0.3.8}/MANIFEST.in

@@ -1,3 +1,4 @@
 recursive-include app/static *
 recursive-include app/templates *.html
+prune app/__pycache__
 global-exclude .DS_Store

{metalist-0.3.6/metalist.egg-info → metalist-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metalist
-Version: 0.3.6
+Version: 0.3.8
 Summary: A minimalist single-user note-taking app with SSR, fast in-memory tree operations, and efficient sync.
 Project-URL: Homepage, https://github.com/evolvingstuff/metalist
 Project-URL: Repository, https://github.com/evolvingstuff/metalist

{metalist-0.3.6 → metalist-0.3.8}/app/api/middleware/auth.py

@@ -20,10 +20,12 @@ class AuthMiddleware(BaseHTTPMiddleware):
         f"{API_PREFIX}/auth/status",
         f"{API_PREFIX}/auth/session",
         f"{API_PREFIX}/auth/namespaces/delete-jobs/",
+        f"{API_PREFIX}/auth/namespaces/rename-jobs/",
         f"{API_PREFIX}/mcp",
         "/mcp-client-v2",
         "/mcp-client",
         "/namespace-deleted",
+        "/namespace-renamed",
         "/static/",  # CSS/JS files needed for login page
         "/favicon.ico",
         "/locked",

{metalist-0.3.6 → metalist-0.3.8}/app/api/routes/auth.py

@@ -47,8 +47,10 @@ from app.services.namespace_switcher import delete_current_namespace
 from app.services.namespace_switcher import delete_namespace
 from app.services.namespace_switcher import open_login_namespace
 from app.services.namespace_switcher import open_or_launch_namespace
+from app.services.namespace_switcher import rename_current_namespace
 from app.services.namespace_switcher import save_namespace_port_profiles
 from app.services.namespace_deletion_jobs import load_namespace_deletion_job
+from app.services.namespace_rename_jobs import load_namespace_rename_job
 from app.server_runtime import NamespaceLaunchProfile
 from app.server_runtime import resolve_namespace_directory
 from app.server_runtime import resolve_namespaced_database_path
@@ -590,6 +592,15 @@ def _require_string_field(payload: dict[str, object], field_name: str) -> str:
     return value
 
 
+def _require_string_field_allow_empty(payload: dict[str, object], field_name: str) -> str:
+    if field_name not in payload:
+        raise HTTPException(status_code=400, detail=f"{field_name} is required")
+    value = payload[field_name]
+    if not isinstance(value, str):
+        raise HTTPException(status_code=400, detail=f"{field_name} must be a string")
+    return value
+
+
 def _require_int_field(payload: dict[str, object], field_name: str) -> int:
     if field_name not in payload:
         raise HTTPException(status_code=400, detail=f"{field_name} is required")
@@ -968,7 +979,8 @@ def save_namespace_ports(
 def _delete_namespace_from_body(*, body: dict[str, object], target_namespace: str) -> dict[str, object]:
     normalized_target_namespace = validate_namespace(namespace=target_namespace)
     confirmed_namespace = _require_string_field(body, "confirmed_namespace")
-    current_password = _require_string_field(body, "current_password")
+    current_password = _require_string_field_allow_empty(body, "current_password")
+    redirect_namespace = _require_string_field(body, "redirect_namespace")
 
     if _namespace_requires_password(namespace=normalized_target_namespace):
         _verify_namespace_password(
@@ -989,6 +1001,7 @@ def _delete_namespace_from_body(*, body: dict[str, object], target_namespace: st
             current_namespace=ACTIVE_NAMESPACE,
             target_namespace=normalized_target_namespace,
             confirmed_namespace=confirmed_namespace,
+            redirect_namespace=redirect_namespace,
         )
     if delete_capture.captured_exception is not None:
         exc = delete_capture.captured_exception
@@ -1019,11 +1032,33 @@ def namespace_delete_preflight(
     target_requires_password = False
     if target_exists:
         target_requires_password = _namespace_requires_password(namespace=target_namespace)
+    catalog = build_namespace_catalog(
+        environ=os.environ,
+        current_namespace=ACTIVE_NAMESPACE,
+    )
+    raw_namespaces = catalog["namespaces"]
+    if not isinstance(raw_namespaces, list):
+        raise RuntimeError("Namespace catalog missing namespaces")
+    redirect_namespaces: list[str] = []
+    for raw_entry in raw_namespaces:
+        if not isinstance(raw_entry, dict):
+            raise RuntimeError("Namespace catalog entry must be an object")
+        namespace = raw_entry["namespace"]
+        if not isinstance(namespace, str) or namespace == "":
+            raise RuntimeError("Namespace catalog entry missing namespace")
+        if namespace != target_namespace:
+            redirect_namespaces.append(namespace)
+    redirect_namespaces.sort()
+    recreates_default = target_namespace == ACTIVE_NAMESPACE and len(redirect_namespaces) == 0
+    if recreates_default:
+        redirect_namespaces.append("default")
     return {
         "target_namespace": target_namespace,
         "target_exists": target_exists,
         "target_requires_password": target_requires_password,
         "is_current_namespace": target_namespace == ACTIVE_NAMESPACE,
+        "redirect_namespaces": redirect_namespaces,
+        "recreates_default": recreates_default,
     }
 
 
@@ -1054,6 +1089,41 @@ def delete_active_namespace(
     )
 
 
+@router.post("/namespaces/rename-current")
+@transactional_route
+def rename_active_namespace(
+    payload: dict[str, object],
+    token: Annotated[str, Depends(_require_auth)],
+):
+    body = _require_body_object(payload)
+    target_namespace = _require_string_field(body, "target_namespace")
+    rename_capture = CapturedExceptionContext(
+        RuntimeError,
+        ValueError,
+        TypeError,
+        FileNotFoundError,
+    )
+    result = None
+    with rename_capture:
+        result = rename_current_namespace(
+            environ=os.environ,
+            current_namespace=ACTIVE_NAMESPACE,
+            target_namespace=target_namespace,
+        )
+    if rename_capture.captured_exception is not None:
+        exc = rename_capture.captured_exception
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    if result is None:
+        raise RuntimeError("Namespace rename did not return a result")
+    return {
+        "source_namespace": result.source_namespace,
+        "target_namespace": result.target_namespace,
+        "redirect_url": result.redirect_url,
+        "rename_job_id": result.rename_job_id,
+        "message": result.message,
+    }
+
+
 @router.get("/namespaces/delete-jobs/{job_id}")
 def namespace_delete_job_status(
     job_id: str,
@@ -1075,6 +1145,25 @@ def namespace_delete_job_status(
     return job_record
 
 
+@router.get("/namespaces/rename-jobs/{job_id}")
+def namespace_rename_job_status(job_id: str):
+    job_record_capture = CapturedExceptionContext(
+        RuntimeError,
+        TypeError,
+        ValueError,
+        FileNotFoundError,
+    )
+    job_record: dict[str, object] | None = None
+    with job_record_capture:
+        job_record = load_namespace_rename_job(job_id=job_id)
+    if job_record_capture.captured_exception is not None:
+        exc = job_record_capture.captured_exception
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    if job_record is None:
+        raise HTTPException(status_code=404, detail=f"Namespace rename job not found: {job_id}")
+    return job_record
+
+
 @router.post("/hydrate", response_model=HydrationStatusResponse)
 @transactional_route
 def hydrate_cache(

{metalist-0.3.6 → metalist-0.3.8}/app/api/routes/backups.py

@@ -717,6 +717,32 @@ def _required_existing_target_launch_profile(*, target_namespace: str) -> Backup
     )
 
 
+def _resolve_same_name_restore_launch_profile(
+    *,
+    backup_path: Path,
+    target_namespace: str,
+    target_exists: bool,
+) -> BackupLaunchProfile:
+    if target_exists:
+        return _required_existing_target_launch_profile(
+            target_namespace=target_namespace,
+        )
+    restored_profile = read_backup_launch_profile(
+        backup_path,
+        expected_namespace=target_namespace,
+    )
+    suggested_profile = _suggest_import_launch_profile(
+        target_namespace=target_namespace,
+        restored_profile=restored_profile,
+    )
+    return BackupLaunchProfile(
+        namespace=target_namespace,
+        port=suggested_profile.port,
+        https_port=suggested_profile.https_port,
+        mcp_port=suggested_profile.mcp_port,
+    )
+
+
 def _backup_profile_from_request(
     *,
     namespace: str,
@@ -920,22 +946,22 @@ def restore_backup_preflight(
     target_exists = _restore_target_exists(target_namespace=target_namespace)
     suggested_profile = None
     port_conflicts: list[str] = []
-    if target_namespace != backup_namespace:
-        if target_exists:
-            target_profile = _required_existing_target_launch_profile(
-                target_namespace=target_namespace,
-            )
-            suggested_profile = _response_profile_from_backup_profile(profile=target_profile)
-            assert suggested_profile is not None
-        else:
+    if target_exists:
+        target_profile = _required_existing_target_launch_profile(
+            target_namespace=target_namespace,
+        )
+        suggested_profile = _response_profile_from_backup_profile(profile=target_profile)
+        assert suggested_profile is not None
+    else:
+        if restored_profile is not None:
             port_conflicts = _collect_import_profile_port_conflicts(
                 target_namespace=target_namespace,
                 launch_profile=restored_profile,
             )
-            suggested_profile = _suggest_import_launch_profile(
-                target_namespace=target_namespace,
-                restored_profile=restored_profile,
-            )
+        suggested_profile = _suggest_import_launch_profile(
+            target_namespace=target_namespace,
+            restored_profile=restored_profile,
+        )
 
     return BackupRestorePreflightResponse(
         backup_namespace=backup_namespace,
@@ -983,10 +1009,22 @@ def restore_backup(
     backup_path = folder_directory / folder_filename
     if not backup_path.exists():
         raise HTTPException(status_code=404, detail=f"Backup not found: {folder_filename}")
+    target_exists = _restore_target_exists(target_namespace=target_namespace)
+    launch_profile = _resolve_same_name_restore_launch_profile(
+        backup_path=backup_path,
+        target_namespace=target_namespace,
+        target_exists=target_exists,
+    )
     if target_namespace == ACTIVE_NAMESPACE:
         maintenance_service.enter_maintenance("Restoring backup")
         try:
             restore_backup_to_paths(backup_path, target_database_path)
+            save_namespace_launch_profile(
+                namespace=target_namespace,
+                port=launch_profile.port,
+                https_port=launch_profile.https_port,
+                mcp_port=launch_profile.mcp_port,
+            )
             _reset_runtime_state_after_restore()
         finally:
             maintenance_service.exit_maintenance()
@@ -995,6 +1033,12 @@ def restore_backup(
         open_namespace_suggested = False
     else:
         restore_backup_to_paths(backup_path, target_database_path)
+        save_namespace_launch_profile(
+            namespace=target_namespace,
+            port=launch_profile.port,
+            https_port=launch_profile.https_port,
+            mcp_port=launch_profile.mcp_port,
+        )
     return BackupRestoreResponse(
         backup_id=payload.backup_id,
         source=payload.source,

{metalist-0.3.6 → metalist-0.3.8}/app/main.py

@@ -34,8 +34,10 @@ from app.security.encryption import set_encryption_required
 from app.server_runtime import resolve_mcp_agent_public_origin
 from app.server_runtime import resolve_https_redirect_url
 from app.server_runtime import resolve_request_host_for_https_redirect
+from app.server_runtime import validate_namespace
 from app.services.exception_capture import CapturedExceptionContext
 from app.services.namespace_deletion_jobs import load_namespace_deletion_job
+from app.services.namespace_rename_jobs import load_namespace_rename_job
 from app.services.namespace_switcher import build_namespace_catalog
 from app.services.namespace_switcher import open_or_launch_namespace
 from app.services.diagnostics import configure_process_diagnostics
@@ -435,36 +437,17 @@ async def maintenance_page(request: Request):
     )
 
 
-def _build_namespace_deleted_links(*, job_id: str, deleted_namespace: str) -> list[dict[str, str]]:
-    catalog = build_namespace_catalog(
-        environ=os.environ,
-        current_namespace=ACTIVE_NAMESPACE,
-    )
-    raw_namespaces = catalog["namespaces"]
-    if not isinstance(raw_namespaces, list):
-        raise RuntimeError("Namespace catalog missing namespaces")
-    links: list[dict[str, str]] = []
-    for entry in raw_namespaces:
-        if not isinstance(entry, dict):
-            raise RuntimeError("Namespace catalog entry must be an object")
-        namespace = entry["namespace"]
-        if not isinstance(namespace, str) or namespace == "":
-            raise RuntimeError("Namespace catalog entry missing namespace")
-        if namespace == deleted_namespace:
-            continue
-        query = urlencode({"job": job_id, "namespace": namespace})
-        link_meta = "Open namespace"
-        if namespace == ACTIVE_NAMESPACE:
-            link_meta = "Already running"
-        links.append(
-            {
-                "namespace": namespace,
-                "label": namespace,
-                "meta": link_meta,
-                "href": f"/namespace-deleted/open?{query}",
-            }
-        )
-    return links
+def _build_namespace_deleted_links(*, job_id: str, redirect_namespace: str) -> list[dict[str, str]]:
+    normalized_redirect_namespace = validate_namespace(namespace=redirect_namespace)
+    query = urlencode({"job": job_id, "namespace": normalized_redirect_namespace})
+    return [
+        {
+            "namespace": normalized_redirect_namespace,
+            "label": normalized_redirect_namespace,
+            "meta": "Selected destination",
+            "href": f"/namespace-deleted/open?{query}",
+        }
+    ]
 
 
 def _resolve_catalog_profile(*, namespace: str) -> tuple[int, int | None, int]:
@@ -543,7 +526,7 @@ async def namespace_deleted_page(request: Request):
     template = templates.get_template("namespace_deleted.html")
     namespace_links = _build_namespace_deleted_links(
         job_id=job_record["job_id"],
-        deleted_namespace=job_record["deleted_namespace"],
+        redirect_namespace=job_record["redirect_namespace"],
     )
     page_state = json.dumps(
         {
@@ -551,6 +534,7 @@ async def namespace_deleted_page(request: Request):
             "deletedNamespace": job_record["deleted_namespace"],
             "initialStatus": job_record["status"],
             "initialError": job_record["error"],
+            "redirectNamespace": job_record["redirect_namespace"],
         }
     )
     return template.render(
@@ -588,7 +572,10 @@ async def namespace_deleted_open_page(request: Request):
         return HTMLResponse(f"Namespace deletion job not found: {job_id}", status_code=404)
     if job_record["status"] == "pending":
         return HTMLResponse("Namespace deletion is still in progress", status_code=409)
-    if namespace == job_record["deleted_namespace"]:
+    if (
+        namespace == job_record["deleted_namespace"]
+        and namespace != job_record["redirect_namespace"]
+    ):
         return HTMLResponse("Deleted namespace is unavailable", status_code=400)
 
     launch_capture = CapturedExceptionContext(
@@ -618,6 +605,75 @@ async def namespace_deleted_open_page(request: Request):
     return response
 
 
+@app.get("/namespace-renamed", response_class=HTMLResponse)
+async def namespace_renamed_page(request: Request):
+    job_id = request.query_params.get("job")
+    if not isinstance(job_id, str) or job_id.strip() == "":
+        return HTMLResponse("Missing namespace rename job", status_code=400)
+    job_record_capture = CapturedExceptionContext(
+        RuntimeError,
+        TypeError,
+        ValueError,
+        FileNotFoundError,
+    )
+    job_record: dict[str, object] | None = None
+    with job_record_capture:
+        job_record = load_namespace_rename_job(job_id=job_id)
+    if job_record_capture.captured_exception is not None:
+        exc = job_record_capture.captured_exception
+        return HTMLResponse(str(exc), status_code=400)
+    if job_record is None:
+        return HTMLResponse(f"Namespace rename job not found: {job_id}", status_code=404)
+
+    page_state = json.dumps(
+        {
+            "jobId": job_record["job_id"],
+            "sourceNamespace": job_record["source_namespace"],
+            "targetNamespace": job_record["target_namespace"],
+            "initialStatus": job_record["status"],
+            "initialError": job_record["error"],
+        }
+    )
+    template = templates.get_template("namespace_renamed.html")
+    return template.render(
+        request=request,
+        version=VERSION,
+        asset_version=ASSET_VERSION,
+        page_title="MetaList - Namespace Renamed",
+        source_namespace=job_record["source_namespace"],
+        target_namespace=job_record["target_namespace"],
+        page_state_json=page_state,
+    )
+
+
+@app.get("/namespace-renamed/open")
+async def namespace_renamed_open_page(request: Request):
+    job_id = request.query_params.get("job")
+    if not isinstance(job_id, str) or job_id.strip() == "":
+        return HTMLResponse("Missing namespace rename job", status_code=400)
+    job_record_capture = CapturedExceptionContext(
+        RuntimeError,
+        TypeError,
+        ValueError,
+        FileNotFoundError,
+    )
+    job_record: dict[str, object] | None = None
+    with job_record_capture:
+        job_record = load_namespace_rename_job(job_id=job_id)
+    if job_record_capture.captured_exception is not None:
+        exc = job_record_capture.captured_exception
+        return HTMLResponse(str(exc), status_code=400)
+    if job_record is None:
+        return HTMLResponse(f"Namespace rename job not found: {job_id}", status_code=404)
+    if job_record["status"] != "succeeded":
+        return HTMLResponse("Namespace rename is not complete", status_code=409)
+    if ACTIVE_NAMESPACE != job_record["target_namespace"]:
+        return HTMLResponse("Renamed namespace is not running here", status_code=409)
+    response = RedirectResponse(url="/?force_reauth=1", status_code=307)
+    clear_auth_cookie(response=response)
+    return response
+
+
 @app.get("/locked", response_class=HTMLResponse)
 async def locked_page(request: Request, db: Annotated[SafeSession, Depends(get_db)]):
     """Render a dedicated locked screen when a session is invalidated."""

{metalist-0.3.6 → metalist-0.3.8}/app/server_runtime.py

@@ -32,6 +32,7 @@ _DEFAULT_KEY_PATH = _DEFAULT_DATABASE_DIRECTORY / "certs" / "metalist-key.pem"
 _DEFAULT_RUNTIME_DIRECTORY = Path(tempfile.gettempdir()) / "metalist-runtime"
 _DEFAULT_NAMESPACES_DIRECTORY_NAME = "namespaces"
 _DEFAULT_NAMESPACE_DELETE_JOBS_DIRECTORY_NAME = "namespace-delete-jobs"
+_DEFAULT_NAMESPACE_RENAME_JOBS_DIRECTORY_NAME = "namespace-rename-jobs"
 _DEFAULT_LOGS_DIRECTORY_NAME = "logs"
 _DEFAULT_NAMESPACE = "default"
 _DEFAULT_HTTP_PORT = 8000
@@ -126,6 +127,10 @@ def resolve_namespace_delete_jobs_directory() -> Path:
     return _DEFAULT_RUNTIME_DIRECTORY / _DEFAULT_NAMESPACE_DELETE_JOBS_DIRECTORY_NAME
 
 
+def resolve_namespace_rename_jobs_directory() -> Path:
+    return _DEFAULT_RUNTIME_DIRECTORY / _DEFAULT_NAMESPACE_RENAME_JOBS_DIRECTORY_NAME
+
+
 def resolve_runtime_logs_directory() -> Path:
     return _DEFAULT_DATABASE_DIRECTORY / _DEFAULT_LOGS_DIRECTORY_NAME
 

{metalist-0.3.6 → metalist-0.3.8}/app/services/namespace_deletion_worker.py

@@ -10,11 +10,13 @@ import time
 import traceback
 
 import app.server_runtime as server_runtime
+from app.server_runtime import save_namespace_launch_profile
 from app.server_runtime import resolve_namespace_directory
 from app.server_runtime import validate_namespace
 from app.services.exception_capture import CapturedExceptionContext
 from app.services.namespace_deletion_jobs import mark_namespace_deletion_job_failed
 from app.services.namespace_deletion_jobs import mark_namespace_deletion_job_succeeded
+from app.services.namespace_switcher import open_or_launch_namespace
 from app.services.windows_process_control import is_process_running as is_windows_process_running
 from app.services.windows_process_control import stop_process as stop_windows_process
 
@@ -30,6 +32,11 @@ def _parse_args() -> argparse.Namespace:
     parser.add_argument("--pid", type=int, required=True)
     parser.add_argument("--namespace", required=True)
     parser.add_argument("--job-id", required=True)
+    parser.add_argument("--replacement-namespace", required=True)
+    parser.add_argument("--replacement-port", type=int, required=True)
+    parser.add_argument("--replacement-https-port", type=int, required=True)
+    parser.add_argument("--replacement-mcp-port", type=int, required=True)
+    parser.add_argument("--recreate-default", action="store_true")
     return parser.parse_args()
 
 
@@ -123,16 +130,38 @@ def _delete_namespace_directory(*, namespace: str) -> None:
     shutil.rmtree(namespace_directory)
 
 
+def _recreate_default_namespace(*, args: argparse.Namespace) -> None:
+    replacement_namespace = validate_namespace(namespace=args.replacement_namespace)
+    if replacement_namespace != server_runtime._DEFAULT_NAMESPACE:
+        raise RuntimeError("Final namespace deletion must recreate default")
+    https_port = args.replacement_https_port
+    if https_port == 0:
+        https_port = None
+    save_namespace_launch_profile(
+        namespace=replacement_namespace,
+        port=args.replacement_port,
+        https_port=https_port,
+        mcp_port=args.replacement_mcp_port,
+    )
+    open_or_launch_namespace(
+        environ=os.environ,
+        current_namespace=None,
+        namespace=replacement_namespace,
+        port=args.replacement_port,
+        https_port=https_port,
+        mcp_port=args.replacement_mcp_port,
+    )
+
+
 def main() -> None:
     args = _parse_args()
     main_capture = CapturedExceptionContext(Exception)
     with main_capture:
         normalized_namespace = validate_namespace(namespace=args.namespace)
-        if normalized_namespace == server_runtime._DEFAULT_NAMESPACE:
-            raise RuntimeError("Default namespace cannot be deleted")
-
         _stop_process(pid=args.pid)
         _delete_namespace_directory(namespace=normalized_namespace)
+        if args.recreate_default:
+            _recreate_default_namespace(args=args)
         mark_namespace_deletion_job_succeeded(job_id=args.job_id)
     if main_capture.captured_exception is not None:
         mark_namespace_deletion_job_failed(

metalist-0.3.8/app/services/namespace_rename_jobs.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import re
+import uuid
+
+from app.server_runtime import resolve_namespace_rename_jobs_directory
+
+
+_JOB_ID_PATTERN = re.compile(r"^[a-f0-9-]{36}$")
+
+
+def create_namespace_rename_job(
+    *,
+    source_namespace: str,
+    target_namespace: str,
+) -> dict[str, str]:
+    if not isinstance(source_namespace, str) or source_namespace == "":
+        raise TypeError("source_namespace must be a non-empty string")
+    if not isinstance(target_namespace, str) or target_namespace == "":
+        raise TypeError("target_namespace must be a non-empty string")
+
+    job_id = str(uuid.uuid4())
+    job_record = {
+        "job_id": job_id,
+        "status": "pending",
+        "source_namespace": source_namespace,
+        "target_namespace": target_namespace,
+        "error": "",
+    }
+    _write_job_record(job_id=job_id, job_record=job_record)
+    return job_record
+
+
+def load_namespace_rename_job(*, job_id: str) -> dict[str, str] | None:
+    normalized_job_id = _validate_job_id(job_id=job_id)
+    job_path = _resolve_job_path(job_id=normalized_job_id)
+    if not job_path.is_file():
+        return None
+    payload = json.loads(job_path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise RuntimeError(f"Namespace rename job is not an object: {job_path}")
+    return _coerce_job_record(payload=payload, job_id=normalized_job_id)
+
+
+def mark_namespace_rename_job_succeeded(*, job_id: str) -> None:
+    job_record = _require_existing_job(job_id=job_id)
+    job_record["status"] = "succeeded"
+    job_record["error"] = ""
+    _write_job_record(job_id=job_id, job_record=job_record)
+
+
+def mark_namespace_rename_job_failed(*, job_id: str, error: str) -> None:
+    if not isinstance(error, str) or error.strip() == "":
+        raise TypeError("error must be a non-empty string")
+    job_record = _require_existing_job(job_id=job_id)
+    job_record["status"] = "failed"
+    job_record["error"] = error.strip()
+    _write_job_record(job_id=job_id, job_record=job_record)
+
+
+def _require_existing_job(*, job_id: str) -> dict[str, str]:
+    job_record = load_namespace_rename_job(job_id=job_id)
+    if job_record is None:
+        raise RuntimeError(f"Namespace rename job not found: {job_id}")
+    return job_record
+
+
+def _validate_job_id(*, job_id: str) -> str:
+    if not isinstance(job_id, str):
+        raise TypeError(f"job_id must be a string, got {type(job_id)}")
+    normalized_job_id = job_id.strip()
+    if _JOB_ID_PATTERN.fullmatch(normalized_job_id) is None:
+        raise RuntimeError(f"Invalid namespace rename job id: {job_id!r}")
+    return normalized_job_id
+
+
+def _resolve_job_path(*, job_id: str) -> Path:
+    jobs_directory = resolve_namespace_rename_jobs_directory()
+    jobs_directory.mkdir(parents=True, exist_ok=True)
+    return jobs_directory / f"{job_id}.json"
+
+
+def _coerce_job_record(*, payload: dict[str, object], job_id: str) -> dict[str, str]:
+    required_fields = ("status", "source_namespace", "target_namespace", "error")
+    for field_name in required_fields:
+        if field_name not in payload:
+            raise RuntimeError(f"Namespace rename job is missing {field_name}: {payload}")
+    status = payload["status"]
+    source_namespace = payload["source_namespace"]
+    target_namespace = payload["target_namespace"]
+    error = payload["error"]
+    if status not in {"pending", "succeeded", "failed"}:
+        raise RuntimeError(f"Namespace rename job has invalid status: {payload}")
+    if not isinstance(source_namespace, str) or source_namespace == "":
+        raise RuntimeError(f"Namespace rename job is missing source_namespace: {payload}")
+    if not isinstance(target_namespace, str) or target_namespace == "":
+        raise RuntimeError(f"Namespace rename job is missing target_namespace: {payload}")
+    if not isinstance(error, str):
+        raise RuntimeError(f"Namespace rename job has invalid error field: {payload}")
+    return {
+        "job_id": job_id,
+        "status": status,
+        "source_namespace": source_namespace,
+        "target_namespace": target_namespace,
+        "error": error,
+    }
+
+
+def _write_job_record(*, job_id: str, job_record: dict[str, str]) -> None:
+    normalized_job_id = _validate_job_id(job_id=job_id)
+    serialized = json.dumps(job_record, indent=2, sort_keys=True)
+    job_path = _resolve_job_path(job_id=normalized_job_id)
+    job_path.write_text(serialized, encoding="utf-8")