Skip to content

feat: 확장 terminal(배지·응답 종류·단계 검산·Read-back) 저장·전달과 계약 pin 6b237b8 [2.15] - #247

Merged
chowon442 merged 3 commits into
devfrom
feat/2.15-v2-terminal-storage
Nov 15, 2026
Merged

chowon442 merged 3 commits into
devfrom
feat/2.15-v2-terminal-storage

Conversation

@chowon442

@chowon442 chowon442 commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

개요

Task 2.15 — proovy-brain 2.07(PR #198, dev 6b237b8)의 확장 terminal을 Server가 저장하고 브라우저로 넘긴다. 새로고침·대화 다시 열기 뒤에도 배지와 단계 검산이 같은 값으로 보인다.

  • 연결 이슈: [2.15] 이슈 없음(2026-11-11·작업 시작 시 재조회)
  • 작업 문서: proovy-brain tasks/phase-2-redesign/15-server-v2-terminal-storage.md(수정하지 않음)

계약 pin

pin commit consumer_version
PIN.json 6b237b82f4de0af34fdd9ee1d7b4a7147f002f4e browser-run-fixtures-v1.1
PIN-terminal-v2.json 같음 terminal-fixtures-v2.1
PIN-activity-v1.json 같음 activity-fixtures-v1.1

저장 위치 매핑 (2026-11-11 결정 기준)

값 위치
응답 배지 assurance_scope chat_messages.assurance_scope (V6, CHECK verified·unverified·not_applicable)
response_kind chat_messages.response_kind (V6, 기본 standard, CHECK)
문제별 검산 solution_checks(전부, source snake_case) chat_messages.solution_checks JSONB (V6) — 아래 "결정과 다른 점" 참고
verified 검산(공개 view 그대로, 단계·disclosure 포함) verified_solutions.verification_summary.solution_check (기존 JSONB) — 새 artifact 1·verified 검산 1·기존 참조 0일 때만
verified_solutions.step_marks artifact chain mark 그대로(리뷰 M1)
Read-back 저장 상한 read_back 완료 Activity만 256KiB, 나머지 16KB(V6, 리뷰 M3)
Read-back ai_run_events의 activity.* kind read_back (다른 Activity와 같음)
  • migration: V6__v2_terminal_fields.sql (기존 마지막 V5 + 1).
  • 기존 행은 response_kind = 'standard', 배지·검산 NULL. 필수 제약은 assurance_scope IS NOT NULL인 행(확장 terminal로 저장한 행)에만 건다: 완료 assistant만, 세 값 함께, 검산 ≤ 20, 재설명은 not_applicable·검산 없음, 응답 배지 = not_applicable을 뺀 집계(오케스트레이터 메모 2026-11-12 결정 (1)).
  • verified_solutions에 새 열 없음. claims direct|supporting 제약은 v2 terminal도 artifact verification summary의 coverage(direct|supporting)로 채우므로 그대로 맞다 — 바꾸지 않았다.
  • 정답·풀이 숨김(결정 (2)): hide_answer는 모든 단계 withheld(설명·수식 null), hide_solution은 단계 빈 배열을 Server가 검사하고 그대로 저장·전달한다.

결정과 다른 점(확인 부탁)

  1. chat_messages.solution_checks 열을 하나 더 만들었다. 결정은 "미검증 응답의 단계 검산은 응답 메시지 response_pages 결과 block으로 보여 준다(2.07 wire 그대로)"였는데, 2.07 wire에서 단계 검산은 result block 안이 아니라 payload 단위 solutionChecks다. response_pages에 넣으면 canonical 본문·content_sha256과 2.07 wire 모양이 바뀐다. event payload(ai_run_events, 16KB 상한)에 두기에는 20문제 × 80단계가 들어가지 않는다. 그래서 V3 verification_summary와 같은 이유로 응답 메시지에 JSONB 열을 두었다. 대화 조회·SSE replay는 이 열 하나로 같은 값을 만든다.
  2. evidence_code는 저장하지 않는다. 2.07 노출 결정에 따라 Brain은 독립 답(evidence_code·값)·check_reason·problem id를 terminal source에도 싣지 않는다(plan 28). Server가 받을 수 없는 값이다. 대신 verified 검산의 문제 단위 값을 verification_summary.solution_check에 둔다.
  3. verified 검산 ↔ Verified Solution 짝짓기: 2.07 wire에는 연결 키가 없어 모호하지 않을 때(새 artifact 1·verified 검산 1·기존 참조 0)만 짝짓는다. step_marks는 덮어쓰지 않는다. Brain source 검산에 solution_id를 싣도록 2.12 확인 필요. 리뷰 반영 내역과 확인 필요 목록은 PR 코멘트 참고.

변경

  • CompletionExtension(신규): Brain browser_solution_check.py와 같은 규칙 — 세 필드 함께, 단계 종류별 허용 결과, ✓ 단계 수식 필수, argue 수식 금지, 설명 SafeMarkdown·출처 마커 금지·제어 문자, disclosure별 withheld, strategy·cross_check·배지 정합, 응답 배지 집계, 재설명 고정 규칙. 저장 철자(snake, null 생략)와 browser 철자(camel, null key 채움) 변환.
  • TerminalModel.Completed·TerminalAcceptance: 확장 필드 수락, 안내 응답 검산 거부(DISPOSITION_STRUCTURE), artifact 짝짓기.
  • RunTerminalService.writeCompletion: V6 열 저장. TerminalReplay.completedPayload: 배지가 있으면 responseKind·assuranceScope·solutionChecks를 붙인다(SSE live·replay·대화 조회 공용).
  • RunReadService·AssistantMessageContent: 대화 조회 assistant에 세 필드(없으면 key 없음, NON_NULL).
  • ChatMessage 엔티티: 세 열 읽기 전용 매핑(쓰기는 terminal JDBC만).
  • ActivityKind.READ_BACK·SourceActivities: reading_back_problems label, 완료 problems[](번호·본문·보기 0 또는 2~5·그림 설명, 탭·줄바꿈 외 제어 문자 거부, 닫힌 object). SSE replay는 저장 event를 그대로 읽으므로 RunStreamService 경로 변경 없이 read_back이 replay된다(테스트로 확인).
  • ConversationRunRequest·Brain 요청: 변경 없음. 2.07은 internal-run-v1을 바꾸지 않았고, Extracted Problem·Answer Type은 Brain 내부 값이라 Server가 전달할 필드가 계약에 없다.
  • 문서: docs/contracts/browser-run-v1.md(v1.1 절), browser-run-sse.md, 사본 README.

검증

로컬(JDK 없음 → eclipse-temurin:21-jdk 컨테이너, README 방식):

  • compileJava compileTestJava 통과.
  • ./gradlew test --tests 'com.proovy.domain.run.{contract,terminal,event,stream}.*' + Postgres(PROOVY_REQUIRE_DB_TESTS=true, 127.0.0.1:21432): 263 tests, 3 failed → 원인 수정. 실패 3건은 테스트 기대값(response-v1·publication-v1 pin commit은 303a9e4 유지, 응답 fixture 수 15→16)이었고 수정 뒤 이 묶음은 다시 돌리지 못했다(아래). RunTerminalServicePostgresTest 45 cases, skipped 0.
    • 새 Postgres 테스트: 2.07 fixture 4종(객관식 검증됨 phase2-verified, 단답형 미검증·검증 대상 아님은 inconclusive-unverified + browser stream 확장값, 재설명 phase2-re-explanation) → 메시지 배지 저장, verified_solutions 행은 검증됨만 1, 대화 조회와 SSE replay의 세 필드가 browser fixture와 같음. 확장 없는 terminal, verified 행 step_marks·solution_check, V6 CHECK 거부, 진행 중 run의 Read-back replay.
    • 계약 테스트: phase2 pair 4종 golden 일치, browser-run v1.1 valid 확장 7개 왕복, invalid 확장 17개 모두 거부, read_back fixture·invalid(답·단계·id·보기 1개·문제 없음) 거부.
  • 전체 ./gradlew test는 로컬에서 메모리 부족으로 중단됐다. CI(전체 suite + Postgres, PROOVY_REQUIRE_DB_TESTS=true)는 통과했다: commit 3c5e8e7, run 43271448604. 수정한 기대값 3건도 CI에서 통과를 확인했다.
  • 유료 live 호출 없음.

작업 문서 체크리스트 결과

  • 계약 사본 교체·PIN(commit·manifest_sha256·consumer_version) 갱신, browser-run-v1.md 갱신
  • 저장 위치: chat_messages 배지·응답 종류 + CHECK(V6), steps → verified_solutions.step_marks, verified_solutions 새 열 없음, claims 제약 확인 — 단 solution_checks 열 추가·evidence_code 미저장(위 "결정과 다른 점")
  • ChatMessage·응답 DTO·VerifiedSolutionInput 바인딩·history에 assuranceScope·responseKind
  • SSE replay에 read_back
  • ConversationRunRequest 보강: 불필요(계약 변경 없음)
  • DoD: [x] fixture 4종 배지 저장·history/SSE 일치·검증됨만 solution 행 / [x] 전체 테스트·CI 통과(run 43271448604)

남은 위험

  • Read-back 완료가 256KiB를 넘으면 거부된다. Brain과 바이트 상한 계약은 2.12 확인 필요.

🤖 Generated with Claude Code

2026-11-15 구현·검증 갱신

최종 구현 HEAD: ee3480f. 독립 리뷰 major 3건을 반영했습니다. 식별 키가 없는 검산·풀이 휴리스틱 연결을 제거하고 artifact 요약·step marks를 보존합니다. 새 Verified Solution 개수를 verified 검산 개수로 제한하며, solution_checks의 공개 문자열에도 signed URL 금지 검사를 적용합니다.

검증: acceptance 계약·회귀 86건, scope 28건, Postgres 47건 및 mirror·browser·activity·stream 관련 검사 통과. 고정 Brain fixture는 변경하지 않았습니다. 최종 HEAD 원격 CI 및 Codex 재리뷰 진행 중입니다.

Brain 연결 키·원문 단계·송신 크기 계약에 관한 후속 책임은 리뷰와 태스크에 남겨 두었습니다.

chowon442 and others added 2 commits November 13, 2026 02:36
- 2.07 계약 사본 교체: browser-run-fixtures-v1.1·terminal-fixtures-v2.1·activity-fixtures-v1.1 (proovy-brain 6b237b8), PIN 3종 갱신
- V6: chat_messages response_kind·assurance_scope·solution_checks와 CHECK(v2 행에만 필수, 배지 집계·재설명 규칙)
- CompletionExtension: Brain browser_solution_check 규칙으로 terminal 확장 검사, 안내 응답 검산 거부
- verified 검산은 새 Verified Solution과 순서대로 짝지어 step_marks·verification_summary.solution_check에 저장
- TerminalReplay 한 함수로 SSE replay·대화 조회에 responseKind·assuranceScope·solutionChecks 전달
- Activity Kind read_back(problems[]) 수락·저장 → SSE replay 포함

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…iB [2.15]

- M1: verified_solutions.step_marks는 artifact chain mark 그대로, 검산(disclosure 적용 view)은 verification_summary.solution_check에
- M2: 새 artifact 1·verified 검산 1·기존 참조 0일 때만 짝짓는다
- M3: read_back 완료 Activity만 ai_run_events 저장 상한 256KiB(V6 CHECK·SourceActivities), 경계 테스트
- m1: 재설명의 새 Verified Solution, 풀이 수를 넘는 verified 검산 거부
- m2: step_index 0..n-1 강제(2.06 규칙)
- m3: ChatMessage.responseKind 초기값 standard
- m6·m7·m8: SafeMarkdown 제어 문자 패턴 공유, 확장 세 필드만 닫힌 목록으로 읽기, 대화 조회 solutionChecks JsonNode 그대로

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@chowon442

Copy link
Copy Markdown
Member Author

리뷰 r2.15 반영 (250e8ea)

Major — 모두 반영

  • M1 verified_solutions.step_marks는 이제 항상 artifact chain mark 그대로다(content_sha256·응답 block step_marks와 대응). 짝지은 검산은 Brain이 보낸 공개 view 그대로(disclosure·단계 포함) verification_summary.solution_check에 둔다. hide_answer·hide_solution도 영구 mark를 덮지 않는다. 테스트: phase2-verified·phase2-hide-answer Postgres 행 확인.
  • M2 연결 키가 없으므로 모호하지 않을 때만 짝짓는다: 새 artifact 1개 · verified 검산 1개 · 기존 참조 0개. 그 밖에는 짝짓지 않는다(검산은 메시지 solution_checks에 모두 남아 화면 영향 없음). 2개 이상 verified 짝짓기 fixture는 artifact를 둘 가진 유효 terminal이 2.07 fixture에 없어 만들지 않았다. 대신 m1 규칙(verified 수 ≤ 풀이 수) 위반 거부와 mixed-scope 짝짓기 테스트를 넣었다.
  • M3 Read-back 완료(activity.completed, kind read_back)만 저장 상한을 256KiB로 올렸다(V6 ck_ai_run_events_payload 재정의 + SourceActivities.maxStoredBytes). 나머지 event는 16KB 그대로다. 경계 테스트: 한글 6,000자 문제 4개(약 72KB)는 저장·replay되고, 20문제 × 20,000자는 거부된다.

Minor

  • m1 반영 — 재설명이 새 Verified Solution을 가져오면 거부, verified 검산 수가 새 artifact + 기존 참조 수를 넘으면 거부(Server가 Brain보다 엄격).
  • m2 반영 — step_index가 0부터 빈틈없이 세는지 강제한다. 2.06 SolutionVerification이 이미 같은 규칙을 강제하므로(solution_verification.py:402) Brain과 어긋나지 않는다.
  • m3 반영 — ChatMessage.responseKind 초기값 "standard".
  • m4 일부 반영 — Server 문서 docs/contracts/browser-run-v1.md에 실제 저장 위치와 결정과 다른 점을 적었다. 작업 문서·spec 08은 proovy-brain에 있고 에이전트가 고치지 않는 규칙이라 반영하지 않음 → 머지 전 오케스트레이터 승인 필요(아래 확인 필요 1).
  • m5 반영하지 않음 — terminal-v2에 phase2-unverified·phase2-not-applicable pair를 추가하는 일은 proovy-brain 계약(읽기 전용) 변경이다. Brain 2.07 후속으로 요청하고 2.18 인수 항목에 넣는 것을 제안한다. 그동안 테스트는 v1 pair + browser stream 확장값을 source 철자로 바꿔 쓴다(변환은 키 snake_case화와 null 제거뿐).
  • m6 일부 반영 — CompletionExtension은 SafeMarkdown.CONTROL을 공유한다. SourceActivities(event package)의 Read-back 패턴은 package 경계 때문에 사본으로 두고 주석으로 같은 집합임을 적었다. 위반 사유는 terminal(MALFORMED/UNSAFE_MARKDOWN)과 activity(ActivityContractViolation)가 경로가 달라 섞이지 않는다.
  • m7 반영 — 확장 세 필드만 떼어 닫힌 목록으로 읽는다. 별도 ObjectMapper 제거(TerminalAcceptance.tree 공유).
  • m8 반영 — AssistantMessageContent.solutionChecks는 JsonNode를 그대로 받는다.

확인 필요 (문서로 정할 수 없어 안전한 쪽으로 정함)

  1. 저장 위치가 2026-11-11 결정 문구와 다르다: 미검증·검증 대상 아님 단계 검산은 chat_messages.solution_checks, verified 단계는 step_marks가 아니라 verification_summary.solution_check(disclosure 적용 view라 영구 mark를 덮지 않음), evidence_code는 Brain이 보내지 않아 미저장. 작업 문서 갱신은 사용자 소관.
  2. 검산 ↔ Verified Solution 연결: Brain terminal source 검산에 solution_id를 실어 달라고 2.12에 요청 필요. 받기 전까지는 1:1일 때만 짝짓는다.
  3. 원문 단계(disclosure 적용 전)가 2.14 재설명에 필요하면 Brain 내부 전용 필드가 필요하다. 지금 Server는 공개 view만 받는다.
  4. Read-back 바이트 상한을 Brain 계약에 둘지(2.12). Server는 256KiB를 넘으면 거부한다.

검증

  • run.{contract,terminal,event,stream}.* + Postgres: 267 tests, Read-back 테스트 1건(Activity 순서: started 먼저) 수정 뒤 RunTerminalServicePostgresTest 46/46 통과(skipped 0).
  • 전체 suite는 CI로 확인(메모리 제약으로 로컬 전체 실행은 하지 않음).

@chowon442
chowon442 merged commit b2a97d7 into dev Nov 15, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant