Docs for key renames: ids and keys in the flow concepts, the rename routes, events and 503s in the API reference, hooks during a rename, sync and run metrics after one; a pinned restore refused for its recorded key names that key in the 409

backend/fluksio/main.py

@@ -67,7 +67,7 @@ from fluksio.flow.resources import (
 from fluksio.flow.runs import RUN_STATE_TTL, RunService, sweep_artifacts
 from fluksio.flow.secrets import init_secrets
 from fluksio.flow.state import MemoryState, RedisState, StateBackend
-from fluksio.flow.store import FlowStore, IdentityChange, InvalidName
+from fluksio.flow.store import FlowStore, IdentityChange, InvalidName, RecordedKey
 from fluksio.flow.tombstones import Tombstones
 from fluksio.flow.watchdog import LoopWatchdog
 from fluksio.flow.workers import PythonWorkerPool
@@ -673,8 +673,10 @@ async def invalid_name(request: Request, exc: InvalidName) -> JSONResponse:  # n
 
 @app.exception_handler(IdentityChange)
 async def identity_change(request: Request, exc: IdentityChange) -> JSONResponse:  # noqa: ARG001
-    """A save that would change an object's id or key, which no save may."""
-    return JSONResponse(status_code=409, content={"detail": str(exc)})
+    """A save that would change an object's id or key, which no save may. A
+    restore refused for its key names the one its history is filed under."""
+    key = {"key": exc.key} if isinstance(exc, RecordedKey) else {}
+    return JSONResponse(status_code=409, content={"detail": str(exc), **key})
 
 
 @app.exception_handler(DeviceUnavailable)

backend/tests/api/routes/test_flow_ids.py

@@ -391,7 +391,7 @@ def test_a_pinned_restore_takes_its_history_back(
         headers=superuser_token_headers,
         json={**plain, "name": f"{key}_b", "id": pin},
     )
-    assert other.status_code == 409
+    assert other.status_code == 409 and other.json()["key"] == key
     restored = client.post(
         f"{FLOWS}/", headers=superuser_token_headers, json={**plain, "id": pin}
     )