docs/plans/persistence.md

인터스티셜 히스토리 + 세션 영속화 — 구현 계획

작성일: 2026-07-06 · 상태: 구현 완료 (2026-07-06, feature/persistence) 검증: pytest 26건 통과(신규 8건 포함) + 서버 재시작 e2e (E01-11 진행 → kill/재기동 → GET 복원 동일 카드 → advance 계속 진행 · 미존재 세션 404) 후속 수정 (2026-07-06, 유저 실플레이 피드백 2회): 오버레이 방식 자체를 폐기 — 연출 컷을 자체 번호를 가진 독립 페이지로 (예: 6 본문 → 7 컷 → 8 본문, total 66 = 61+5). 번호는 서버(router _page_index)가 권위, 컷 페이지 번호 = progress.index - 1. 프론트의 오버레이/pendingPage/클릭가드 로직 전부 제거 → 일반 페이지 흐름으로 단순화. Node DOM 스텁 시뮬레이션으로 정/역방향·좌클릭 통과 검증 선행 결정 (유저 확정):

• 포켓(채팅) 중간 상태는 영속화하지 않는다 — 서버 재시작/복원 시 포켓은 버리고 읽기 화면으로
• 복원 범위는 "현재 페이지부터 이어 읽기"만 — 뒤로가기 히스토리는 새로고침 시 포기 권장안 채택: SQLite + 스냅샷 + 매 변경 즉시 쓰기(write-through) + localStorage 세션 ID + 콘텐츠 버전 스탬프로 무효화

문제 정의

1. 인터스티셜 뒤로가기 버그: 연출 컷이 히스토리의 페이지가 아니라 일회성 오버레이라서, 뒤로 넘기면 이미지가 건너뛰어지고 이전 스크립트가 나온다. 의도는 정방향과 동일하게 "스크립트 → 이미지 페이지 → 스크립트"가 역방향에서도 유지되는 것.
2. 영속화 부재: 플레이 세션이 3층 모두 휘발성 — router._sessions(파이썬 dict) · ADK InMemorySessionService · 브라우저 SID(JS 변수). 새로고침이면 세션 ID를 잃고, 서버 재시작이면 전 유저 진행이 사라진다. CLAUDE.md 권위 원칙("현재 유저의 서사 위치 권위: DB play_session.current_state_id")이 예정한 DB가 아직 없다.

설계 핵심

복원의 함정 — _enter() 부수효과

StoryEngine._enter()는 진입 시 쇠약도 증가·축 적용·앎 확립을 수행한다. 복원을 _enter(current_id) 재호출로 구현하면 상태가 이중 적용된다. 따라서 복원은 부수효과 없는 전용 경로로: 필드를 직접 복원하고, 현재 카드의 StepResult는 렌더 전용 메서드로 재구성한다 (_visible_narration + card.choices는 순수 조회).

스냅샷 페이로드 (JSON 직렬화 — 전 필드 int/str/bool/list)

{
  "story":  {"current_id": "E04-07", "visited": [...], "preset_branch": null, "ending_id": null},
  "hidden": {"trust_score": 24, "doubt_score": 12, "frailty": 3,
             "awareness_established": true, "axis_log": [...]}
}

• ending_id: 엔딩 도달 세션도 복원 대상 (새로고침 시 엔딩 화면 유지). 복원 시 chapter.ending_rules에서 id로 역조회
• 포켓 진행 중 저장분은 없다 — 포켓 안의 증분은 close 커밋 후에만 영속 상태에 반영 (기존 단일 경로 유지). 포켓 도중 서버가 죽으면 그 대화의 신뢰축 증분은 유실된다 (승인된 트레이드오프)
• 기존 HiddenState.to_session()은 포켓 전용(부분·키 상이)이므로 재사용하지 않고 스냅샷 메서드를 별도 추가

콘텐츠 버전 스탬프

• ContentRepository에 content_version 프로퍼티: chapter.id + 전역 순서의 카드 ID 목록을 sha256 해시
• 저장 시 스탬프, 복원 시 불일치면 무효화(404 → 프론트가 새 세션 시작). 카드 본문만 바뀐 경우는 잡지 못하지만(ID/순서 동일) 복원이 깨지지는 않으므로 데모 수용

저장 시점 (write-through)

영속 상태가 바뀌는 모든 지점에서 즉시 저장 — POST /session(생성) · advance · choose · pocket/turn(수렴 커밋 시) · pocket/close. pocket/open은 영속 상태 무변경이라 저장 없음.

동시성·수명

• uvicorn 워커 1개 전제 유지 (인메모리 캐시 + ADK InMemory 세션 때문). SQLite는 WAL 모드
• 같은 세션 동시 접근은 마지막 쓰기 승리 (데모 수용)
• 서버 기동 시 30일 미갱신 세션 purge

변경 파일 목록

A. 인터스티셜 히스토리 (버그 수정 — 프론트 단독)

파일	변경
web/index.html	히스토리 항목을 2종으로 타입화: {kind:'page', html, progress, ep} · {kind:'inter', image, caption, progress, ep}. ① showStep(): step.image 있으면 inter 항목을 먼저 push하고 오버레이 표시, 오버레이 클릭 시 page 항목 push + 렌더 ② go(): 커서 이동을 공통 renderEntry(cursor)로 통일 — inter 항목이면 오버레이 표시, page 항목이면 HTML 복원 + 오버레이 닫기 ③ 브라우징 중 오버레이 클릭 = go(+1) (오버레이가 내비 존을 덮으므로; ← 키는 계속 동작) ④ choose()의 스냅샷 갱신(history[cursor].html)은 page 항목에만 닿으므로 그대로

B. 영속화

파일	변경
engine/services/state.py	HiddenState.snapshot() -> dict / HiddenState.from_snapshot(d) 추가 (전 필드. to_session()과 별개 — 포켓 경로 불변)
engine/services/story.py	① snapshot() -> dict (story 파트) ② StoryEngine.restore(repo, snap) -> StoryEngine 클래스메서드 — 부수효과 없이 필드 직접 복원 ③ current_step() -> StepResult — 현재 카드/엔딩의 StepResult를 렌더 전용으로 재구성
engine/repositories/content.py	content_version 프로퍼티 (sha256 스탬프)
engine/repositories/play_session.py	신규. stdlib sqlite3, WAL. 테이블 play_session(sid TEXT PK, payload TEXT, content_version TEXT, updated_at TEXT). 메서드: save(sid, payload, version) / `load(sid, version) -> dict
engine/router.py	① PlaySessionRepository(ROOT/"data"/"sessions.db") 생성 + 기동 시 purge() ② _sessions dict는 캐시로 유지, _get() 미스 시 저장소에서 로드 → StoryEngine.restore + current_step()으로 PlaySession 재구성 (pocket_sid=None — 포켓 폐기) ③ 저장 헬퍼 _save(sid, ps)를 생성/advance/choose/pocket 수렴/close에 write-through
web/index.html	① 기동 시 localStorage.carmilla_sid 있으면 GET /api/session/{sid} 시도 — 성공 시 표지 버튼이 "이어 읽기"로 동작(새 세션 생성 생략, 현재 페이지부터), 404면 sid 폐기 후 기존 흐름 ② 세션 생성 시 sid를 localStorage에 저장 ③ 엔딩 "다시, 처음의 밤으로" 클릭 시 sid 제거 후 reload
.gitignore	data/ 추가
tests/test_persistence.py	신규. ① 스냅샷→복원 라운드트립: 몇 카드 진행 후 복원했을 때 current_id/숨은 상태/진행도 동일 ② 복원이 쇠약도·축을 재적용하지 않음 (핵심 회귀) ③ 엔딩 세션 복원 ④ 저장소 save/load + 버전 불일치 시 None ⑤ 라우터 레벨: _sessions 캐시 비운 뒤(재시작 모사) GET으로 복원되고 포켓은 닫혀 있음
docs/contract/demo_api.md	GET /api/session/{sid}가 복원 진입점임을 명시 (404 = 미존재 또는 콘텐츠 버전 불일치 → 새 세션 생성할 것). 포켓 비영속 명시
docs/plans/persistence.md	본 문서

변경하지 않는 것

• engine/app.py — ADK InMemorySessionService 유지 (포켓 비영속 결정에 따라 SqliteSessionService 불필요)
• engine/services/pocket.py — 포켓 커밋 단일 경로 불변
• content/ — 무변경 (콘텐츠 커밋 금지 규칙)

작업 순서

1. P1 — 인터스티셜 히스토리 (web/index.html 단독, 서버 무관) → 브라우저에서 정/역방향 수동 확인
2. P2 — 스냅샷/복원 엔진 (state.py, story.py) + 단위 테스트 (부수효과 미재적용 회귀 포함)
3. P3 — SQLite 저장소 + 라우터 write-through/복원 (play_session.py, content.py, router.py) + 라우터 테스트
4. P4 — 프론트 이어 읽기 (web/index.html localStorage) → 새로고침·서버 재시작 후 이어 읽기 수동 확인
5. P5 — 문서 갱신 (demo_api.md, ARCHITECTURE.md 치트시트 1줄)

검증: pytest tests/ -q 전건 통과 + 수동 시나리오 3종 (① 이미지 페이지 뒤로가기/앞으로가기 ② 새로고침 후 이어 읽기 ③ uvicorn 재시작 후 이어 읽기 — 포켓 중이었다면 읽기 화면으로).

리스크 / 한계 (승인된 트레이드오프 포함)

• 포켓 도중 서버 사망 시 그 대화의 신뢰축 증분 유실 (포켓 비영속 결정의 귀결)
• 새로고침 시 뒤로가기 히스토리·선택 결과 산문은 소실, 현재 페이지부터 (결정 ⑤)
• 카드 본문만 바뀐 콘텐츠 갱신은 버전 스탬프가 감지 못함 (ID/순서 동일 시) — 복원은 안 깨짐
• 멀티 워커/멀티 프로세스는 여전히 비지원 (ADK 세션·캐시가 인메모리)