[rustjava-upstream-sync-approach-plan] docs: settle upstream sync approach (19 conflicts, 7 staged rounds)

[Jun025]

무엇을 / 왜

티켓 rustjava-upstream-sync-approach-plan. upstream 동기화의 접근안(설계) 확정.
★머지 실행 0 · 충돌 해소 0 · 코드 변경 0 — 전부 merge-tree/show/grep 읽기전용 조회.

정본: docs/upstream-sync-approach.md. STATE.md ## 다음 ① 에 요약을 심었다.

재실측 — 선행(2026-08-15) 수치는 낡았다

축	선행	이번
rev-list --left-right --count origin/main...upstream/main	9 32	10 33
origin tip / upstream tip	2e61e93 / 95ebc5c	85f294a / ba5797b
충돌 파일	17	19

증분 2건의 원인은 upstream 신규 커밋 ba5797b(dlunch#201, 319파일 +20,118/−5,729) 하나다.
교차확인: 선행 tip 쌍(2e61e93 vs 95ebc5c)으로 다시 돌리면 지금도 17 ⇒ 선행 수치는
그 시점에 옳았고 upstream 이 움직여서 바뀌었다. ⇒ ★충돌 목록은 반감기가 짧다.

baseline green: cargo fmt --all -- --check rc=0 · cargo test --all 149 passed / 0 failed / 1 ignored.

처분표 요약

upstream 채택 13 · 양쪽 병합 5 · 재생성 1(Cargo.lock) · 우리 유지 0 · 별 회차 0.

★선행 전제 2건을 실측으로 정정했다

1. 「PR [rustjava-classfile-parse-error-propagation] fix: unreadable class files raise ClassFormatError instead of panicking #3·[rustjava-unsupported-charset-exception] Throw UnsupportedEncodingException instead of panicking on unknown charsets #5 와 upstream 이 정면 충돌」은 과대평가다. 근거로 지목된 add/add 두 파일
   (unsupported_encoding_exception.rs · class_format_error.rs)의 충돌 hunk를 전량 확인한 결과
   의미 차이 0 — 차이는 ba5797b 접근플래그 스윕과 Ok(()) 문체뿐이다.
   진짜 설계 결정은 classfile/src/error.rs 한 파일이고, 거기서도 upstream 이 이긴다
   (Java 관측면 예외 4종 대 1종). PR [rustjava-classfile-parse-error-propagation] fix: unreadable class files raise ClassFormatError instead of panicking #3 의 목적은 upstream 에서도 그대로 성립 = 삼킴.
2. charset 퇴행 범위는 input_stream_reader.rs 하나다. upstream 이 String::decode_str/
   encode_str 에서 동일한 charset 집합과 동일한 별칭 정규화를 독립 구현했다
   (UTF-8|UTF8 · EUC-KR|EUCKR|KS-C-5601-1987|MS949|CP949 · ISO-8859-1|LATIN1 · US-ASCII|ASCII).
   ★게다가 기본 charset 경로에서 폴백해 JDK 규격상 upstream 이 더 옳다(우리는 네 경로 전부에서 던진다).

★★충돌 목록에 «없는» 파일이 더 위험하다

merge-tree 는 충돌만 보고한다. 아래 셋은 충돌 0으로 조용히 머지된 뒤 깨진다.

자리	무엇이 깨지나
tests/test_class_format.rs	우리 전용이라 충돌 없이 머지된 뒤 4건 중 3건 실패 — "Truncated"/"tag 18"/"magic" 문구 단정 ↔ upstream 평문 "Invalid class file"
Cargo.toml ×2 vs thread.rs	★tracing 함정: Cargo.toml 은 조용히 우리 쪽(PR #4, attributes 피처 없음) 으로 머지되는데 upstream thread.rs 에는 #[tracing::instrument] 가 있다 ⇒ 그대로 취하면 컴파일 파괴, 피처를 되살려 고치면 PR #4 통째 되돌림
java_runtime/src/charset.rs	충돌 없이 살아남지만 호출자를 잃으면 dead code → clippy -D warnings red

회귀 잠금

★test_data/UnsupportedCharset.class+.txt 는 이미 실재하고 이미 돈다 — tests/test_class.rs 가
test_data/*.class 를 디렉터리 스캔으로 자동 발견하고 기대 출력에 3 / aéb 가 박혀 있어
ISO-8859-1 의 InputStreamReader 통과를 종단 잠금한다(드라이버는 양쪽 동일 = 충돌 없음).
추가로 이식 3건 + US-ASCII Reader 잠금 신규 1건.

단계 분할 — ★커밋 수로 자르지 마라

컷별 merge-tree 실측: ★19충돌 중 16이 앞쪽 7커밋(dlunch#173~dlunch#180)에서 발생하고, 뒤 26커밋이 더하는 것은 3뿐이다.
⇒ 「32커밋 4등분」류는 1회차에 16충돌을 다 만나고 나머지는 빈손 = 무의미. 축으로 7회차:

회차	컷	커밋	diff	새 충돌	축
S1	1f356ae	5	66f +5,233/−149	2	tracing / PR #4
S2	af4f6f8	1	62f +3,245/−366	+5	charset / PR #5
S3	822504b	1	69f +2,127/−356	+9	오류 분류 / PR #3
S4	3296139	8	50f +4,418/−187	0	GlobalRef · CLI
S5	c4665b0	6	171f +33,138/−1,058	0	Java 1.2 API
S6	95ebc5c	11	142f +17,593/−483	0	regex · Formatter · logging
S7	ba5797b	1	319f +20,118/−5,729	+3	접근플래그 · 디스패치 스윕

★S1~S3 이 판단의 전부다. S4~S7 은 우리 해소분이 0이라 검수는 green + 「해소가 정말 0인가」의
증명으로 짧게 끝난다 — 회차가 커도 검수가 읽는 양은 작다(티켓의 「검수가 실제로 읽을 수 있는 양」).

green 기준은 전 회차 CI rust.yml 4종 동일 + 회차별 추가 조건(문서 §5).

경계 준수

• git merge 실행 0 · 코드 변경 0 · 변경 파일 = STATE.md · REPORT.md · docs/upstream-sync-approach.md
• upstream(dlunch/RustJava) 발신 0 — fetch 와 읽기 조회만
• PR [rustjava-claude-md-prune] docs: prune autonomous-sop, add self-report limits + Goal/Constraints/DoD #8 무접촉 · main 무접촉 · 리베이스/force-push/git gc/--no-verify 0
• 모든 gh 호출에 -R Jun025/RustJava 명시

★머지 금지 — 게이트③은 별 *-merge 티켓 몫.