런타임 계약과 학습자 흐름 보강

docs/guides/architecture.md

@@ -141,7 +141,9 @@ vignette/
 | L6 | 직전 K턴 맥락(히스토리) + 이번 발화(L5) | ❌ | 상담자=user, 내담자(자기)=assistant 매핑 |
 
 메시지 순서: `system(L0+L1, cache)` → `system(L2, cache)` → `system(L3)` → `system(L4)` →
-assistant/user 히스토리(L6) → `user(이번 마스킹 발화, L5)`. 게이트웨이는 마지막 user를 stdin으로 주입한다.
+assistant/user 히스토리(L6) → `user(이번 마스킹 발화, L5)`. 현재 Python gateway의
+`_split_messages()` 경계는 system 묶음과 마지막 user payload만 소비한다. L6의 system 외
+history를 실제 프롬프트에 직렬화하는 변경은 별도 프롬프트 동작 패치로 다룬다.
 
 **안전 불변식**(`L0_SAFETY`, docstring R4/R5/M6):
 
@@ -215,7 +217,7 @@ RBAC×AIView로 차단된다. 이 모듈은 평가 신호만 산출한다.
   supervisor rationale/critique + alternative_utterances. `_deep_schema()`.
 - 정답 라벨 enum은 `app/taxonomy.py`가 단일 원천(SoT). LLM 출력은 enum으로 안전 파싱(미지값 폐기,
   `_parse_technique`/`_parse_client_state`). 게이트웨이 structured 우선, 없으면 text에서 JSON 추출
-  (`_structured_payload`, 코드펜스 관용).
+  (`structured_payload_from_response()`, 코드펜스 관용).
 - evaluator structured 결과는 `evaluate_turn()`/`evaluate_session()` 경계에서 canonical
   `GenerateRequest` SHA-256 키의 인메모리 semantic cache로 재사용할 수 있다. `/admin/usage`는
   cache key·prompt·completion 없이 enabled/entries/hits/misses/stores/evictions/requests/hit_rate와
@@ -426,13 +428,19 @@ GET  {ENGINE_URL}/ready|/health — readiness/liveness
 - 단일 프로세스(uvicorn) 가정의 단순 dict. 멀티워커에선 DB가 SoR이므로 무방.
 - 영속/폴백 분기는 `app/runtime_policy.py`(`runtime_fallback_allowed` / `require_runtime_fallback_allowed`)가
   게이트. 라우트는 `session_persistence`(DB) → 실패 시 store(in-proc) 순으로 시도한다.
+- 회기 평가 저장은 `SessionEvaluationWrite`가 `status/source/scope/stage/payload/error` write packet을
+  소유한다. `routes/sessions.py`와 `routes/eval.py`는 같은 named packet을 만들어 저장하고, DB SQL과
+  fallback cache record는 `session_persistence.py`가 유지한다.
 
 ### 2.12 페르소나 카탈로그 — `app/persona_repository.py`
 
 DB `app.persona_card`가 승인 페르소나의 SoR. 이 모듈이 in-proc `PersonaCard`와 DB 행을 잇는 경계다.
 브라우저-facing persona catalog/review/draft/source/evidence DTO와 deterministic mapper는
-`app/persona_read_model.py`가 소유한다. `routes/personas.py`는 route/auth, teacher/admin gate,
-DB repository 호출, RAG source 등록, LLM draft generation, HTTP error mapping을 유지한다.
+`app/persona_read_model.py`가 소유한다. draft generation structured schema, prompt bundle
+id/version/hash, `GenerateResponse` payload extraction, generated draft default/coercion은
+`app/persona_generation_contract.py`가 소유한다. `routes/personas.py`는 route/auth,
+teacher/admin gate, DB repository 호출, RAG source 등록, engine invocation, provenance assembly,
+HTTP error mapping을 유지한다.
 
 - `load_file_personas()` / `built_in_personas()` — in-code P1~P3과 저장소 `data/personas/P4~P7.json`을 deterministic catalog로 합친다.
 - `materialize_seed_personas()` — built-in P1~P7을 초기 승인 카탈로그로 누락분만 insert(admin 롤). `ON CONFLICT DO NOTHING`이므로 교수 편집본을 덮어쓰거나 `archived` 보관본을 재승인하지 않는다.
@@ -476,7 +484,8 @@ cd apps/api && uvicorn engine_gateway.gateway:app --host 0.0.0.0 --port 9099
 
 - **상주 풀** `/session`, `/session/{sid}/turn`, `/session/{sid}`(DELETE) — 회기 단위 프로세스.
 - **stateless 어댑터**(engine_client 계약과 정합):
-  - `POST /v1/generate` — `EngineMessage[]` → `_split_messages()`로 (system_prompt, last_user) 분리
+  - `POST /v1/generate` — `EngineMessage[]` → `_split_messages()`로
+    `GatewayPromptParts(system_prompt, user_payload)` 분리
     → `--system-prompt`로 주입, 마지막 user를 stdin content로. structured_schema는
     `_inject_schema()`로 system에 JSON 준수 지시 주입(claude -p는 response_format 미지원이라 차선).
   - `POST /v1/stream` — `turn_stream()`이 assistant 텍스트 델타를 즉시 yield → SSE
@@ -488,9 +497,10 @@ cd apps/api && uvicorn engine_gateway.gateway:app --host 0.0.0.0 --port 9099
 provider 라우팅 모드는 `ENGINE_MODE`(`app/config.py`)로 선택: `claude_api`(기본, Anthropic Messages API
 직결) / `claude_cli`(로컬 상주 풀) / `openai`(폴백/평가 보조) / `solar`(국내, PII 민감구간 inference_geo:kr).
 
-> 포트 주의: 게이트웨이 docstring 예시는 `:9099`이고, `app/config.py`의 `engine_url` 기본값은
-> compose 서비스명 기반 `http://engine:8100`이다. 로컬에서는 `ENGINE_URL`을 게이트웨이 실제 포트
-> (예: `http://127.0.0.1:9099`)로 맞춰 주입한다.
+> 포트 주의: 게이트웨이 docstring 예시는 `:9099`이고, `app/config.py`의 bare Settings fallback은
+> legacy compose 서비스명 기반 `http://engine:8100`이다. 현재 지원 compose/local runtime은
+> `ENGINE_URL`을 실제 host gateway 포트(예: `http://host.docker.internal:9099` 또는
+> `http://127.0.0.1:9099`)로 override한다.
 
 ---