docs(deploy): document user-owned session cutover

docker/cutover-legacy-sessions.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Archive exactly three legacy filesystem sessions before optionally deleting them.
+# This helper is deliberately inert unless --delete is supplied after archive verification.
+set -euo pipefail
+
+usage() {
+  echo "usage: $0 [--delete] SOURCE_SESSIONS_DIR BACKUP.tar SESSION_ID SESSION_ID SESSION_ID" >&2
+  exit 2
+}
+
+delete_after_backup=false
+if [[ ${1:-} == "--delete" ]]; then
+  delete_after_backup=true
+  shift
+fi
+[[ $# -eq 5 ]] || usage
+
+source_dir=$1
+backup=$2
+shift 2
+ids=("$@")
+
+[[ -d $source_dir ]] || { echo "legacy session root is not a directory" >&2; exit 1; }
+[[ ! -e $backup ]] || { echo "backup already exists; refusing to overwrite it" >&2; exit 1; }
+[[ ${ids[0]} != "${ids[1]}" && ${ids[0]} != "${ids[2]}" && ${ids[1]} != "${ids[2]}" ]] \
+  || { echo "exactly three distinct legacy session IDs are required" >&2; exit 1; }
+
+paths=()
+for id in "${ids[@]}"; do
+  [[ $id =~ ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$ ]] \
+    || { echo "invalid legacy session ID: $id" >&2; exit 1; }
+  [[ -f "$source_dir/$id/session_manifest.yaml" ]] \
+    || { echo "legacy session manifest is missing: $id" >&2; exit 1; }
+  paths+=("$id")
+done
+
+tar --create --file "$backup" --directory "$source_dir" -- "${paths[@]}"
+tar --list --file "$backup" >/dev/null
+sha256sum "$backup" >"$backup.sha256"
+echo "verified backup: $backup"
+echo "checksum: $backup.sha256"
+
+if ! $delete_after_backup; then
+  echo "no legacy sessions deleted; review the archive, then rerun with --delete during maintenance" >&2
+  exit 0
+fi
+
+for id in "${ids[@]}"; do
+  rm -rf -- "$source_dir/$id"
+done
+echo "deleted exactly three archived legacy sessions"