상태판·가이드와 검증 증거를 동기화

docs/guides/local-development.md

@@ -498,7 +498,7 @@ py -3.11 scripts\sync-persona-sources.py --help
 
 ### 3.6 개선관리 migration 17과 프로토콜 레지스트리
 
-새 Postgres volume은 `infra/db/init/`의 번호순 init으로 migration 17까지 적용한다. 이미 존재하는 DB는
+새 Postgres volume은 `infra/db/init/`의 번호순 init으로 migration 21까지 적용한다. 이미 존재하는 DB는
 애플리케이션 역할이 startup에서 테이블을 만들지 않으므로 owner DSN으로 한 번 적용해야 한다.
 
 ```powershell
@@ -514,6 +514,26 @@ psql.exe "$env:VIGNETTE_OWNER_DATABASE_URL" -v ON_ERROR_STOP=1 --single-transact
 활성화는 라이선스·`external_llm_ok` 검증과 evaluator-only RAG 색인이 한 트랜잭션에서 성공해야 끝난다.
 라이선스 C/D는 외부 LLM 사용을 허용할 수 없다.
 
+### 3.7 단일 활성 회기 migration 21
+
+같은 학습자·페르소나 케이스는 미종료 회기를 하나만 가질 수 있다. 기존 DB에 migration 21을 적용하기 전에는
+owner DSN으로 아래 **읽기 전용** 점검을 먼저 실행한다. 중복 row 또는 실패 후 남은 invalid/wrong target index가
+있으면 임의 종료·삭제·DROP 하지 말고 보존/복구 방식을 소유자가 결정한다.
+
+```powershell
+psql.exe "$env:VIGNETTE_OWNER_DATABASE_URL" -v ON_ERROR_STOP=1 -c "SELECT learner_id, persona_id, count(*) FROM app.sessions WHERE ended_at IS NULL AND persona_id IS NOT NULL GROUP BY learner_id, persona_id HAVING count(*) > 1;"
+psql.exe "$env:VIGNETTE_OWNER_DATABASE_URL" -v ON_ERROR_STOP=1 -c "SELECT c.relname, i.indisvalid, i.indisready, i.indisunique, pg_get_indexdef(i.indexrelid) AS definition FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace JOIN pg_index i ON i.indexrelid = c.oid WHERE n.nspname = 'app' AND c.relname = 'uq_sessions_one_active_learner_persona';"
+```
+
+두 결과가 비어 있거나 target index가 valid/ready/unique이고 정의가 일치할 때만 owner가 online index를 적용한다.
+본 migration은 pre/postcondition으로 같은 검사를 다시 하며, `CREATE INDEX CONCURRENTLY`를 쓰므로
+`--single-transaction`을 붙이면 안 된다.
+
+```powershell
+psql.exe "$env:VIGNETTE_OWNER_DATABASE_URL" -v ON_ERROR_STOP=1 `
+  -f infra\db\init\21_single_active_session.sql
+```
+
 ---
 
 ## 4. 웹(프런트엔드) 실행