정식 승격 상태판과 증거를 동기화

docs/guides/local-development.md

@@ -91,13 +91,29 @@ prod API 8001, web preview 5174, engine gateway 9099, cloudflared tunnel을 검
   worktree를 만들고, 그 root 내부 registrar에 `-StableSourceRoot`를 명시해 두 task를 승격한다.
 
       $releaseRoot = 'D:\workspace\vignette-public-runtime-<commit>'
+      $userUploadDir = Join-Path $env:LOCALAPPDATA 'Vignette\public-runtime\uploads'
+      $uploadStateDir = Join-Path $env:LOCALAPPDATA 'Vignette\public-runtime\private-state'
+      $uploadManifestSha = '<initializer가 출력한 64자리 sha256>'
+      $uploadManifestPath = Join-Path $uploadStateDir "public-avatar-upload-$uploadManifestSha.json"
+      $uploadFreezePath = Join-Path $uploadStateDir 'avatar-cutover.freeze.json'
       $bootRegistrar = Join-Path $releaseRoot 'scripts\register-boot-task.ps1'
-      & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $bootRegistrar -StableSourceRoot $releaseRoot
+      & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $bootRegistrar `
+        -StableSourceRoot $releaseRoot -UserUploadDir $userUploadDir `
+        -UserUploadManifestPath $uploadManifestPath `
+        -ExpectedUserUploadManifestSha256 $uploadManifestSha `
+        -UserUploadWriteFreezePath $uploadFreezePath
       $watchdogInstaller = Join-Path $releaseRoot 'scripts\install-public-runtime-task.ps1'
-      & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $watchdogInstaller -StableSourceRoot $releaseRoot -IntervalMinutes 5
+      & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $watchdogInstaller `
+        -StableSourceRoot $releaseRoot -UserUploadDir $userUploadDir `
+        -UserUploadManifestPath $uploadManifestPath `
+        -ExpectedUserUploadManifestSha256 $uploadManifestSha `
+        -UserUploadWriteFreezePath $uploadFreezePath -IntervalMinutes 5
 
 - `VignettePublicRuntime`은 로그온 Docker/DB 복구, `VignettePublicRuntimeWatchdog`은 로그온+5분 반복 health/recovery다.
-- 두 task action은 release root와 Git commit/tree, boot 또는 watchdog SHA-256, start script SHA-256을 고정한다.
+- 두 task action은 release root와 Git commit/tree, boot 또는 watchdog SHA-256, start script SHA-256,
+  source 밖의 절대 `USER_UPLOAD_DIR`, private migration manifest SHA, source/upload root 밖의 freeze path를 고정한다.
+  consumer는 빈 upload root를 만들지 않으며 watchdog `-CheckOnly`는 정확한 listener PID의 cwd/env와 현재 DB가 참조하는
+  모든 profile avatar의 존재·regular/no-reparse/readability를 다시 증명한다.
   등록 뒤 action marker와 working directory를 읽어 검증하기 전에는 `RunNow`를 호출하지 않는다.
 - secret은 task 인자에 넣지 않는다. API secret은 stable release의 `apps/api/.env`, cloudflared/Claude CLI credential은
   사용자 profile에 둔다. `.env` 내용을 console이나 evidence에 출력하지 않는다.
@@ -368,8 +384,13 @@ C:\Users\encep\AppData\Local\Programs\Python\Python311\python.exe scripts\mainta
 - 신규 사용자 또는 온보딩 미완료 사용자는 로그인 직후 `/onboarding`에서 닉네임, 자기소개,
   선택 아바타 이미지, 이름, 소속, 학과, 학년/직위, 전화번호, 주소/수령지와 약관·개인정보
   동의를 저장해야 역할 홈으로 이동한다. 학습자 회기 시작은 온보딩 완료와 동의가 모두 있어야 한다.
-- 프로필 아바타 업로드는 API 작업 디렉터리 기준 `USER_UPLOAD_DIR`(기본 `uploads`) 아래
-  `profile-avatars/`에 저장되고, `/uploads/profile-avatars/...` URL로 서빙된다.
+- 프로필 아바타 업로드는 `USER_UPLOAD_DIR` 아래 `profile-avatars/`에 저장되고,
+  `/uploads/profile-avatars/...` URL로 서빙된다. 로컬 dev에서 변수를 생략하면 API 작업 디렉터리 기준
+  `uploads`를 쓰지만, Windows public runtime은 release root 밖의 절대
+  `%LOCALAPPDATA%\Vignette\public-runtime\uploads`를 task와 API process environment에 명시한다. API는 전체 root가
+  아니라 `profile-avatars`만 static mount하므로 private `multimodal-audio`가 `/uploads`로 노출되지 않는다. public
+  runtime의 manifest/freeze는 upload root 밖 private state directory에 두며, 정확한 초기화·cutover 순서는
+  `docs/ops/public-runtime-watchdog.md`를 따른다.
 
 > 주의(이메일 도메인): 이 제한은 dev-login·SAML 조직 정책에만 적용된다. dev-login은
 > 이메일 도메인이 `AUTH_ALLOWED_EMAIL_DOMAINS`에 있어야 한다. 예: `learner@hs.ac.kr`.