Task #52: profile --include-pet opt-in과 Full Profile v2 pet 계약 구현

[postmelee]

요약

• 대상 타스크: Issue #52의 profile --include-pet opt-in과 Full Profile v2 custom pet 계약입니다.
• 왜: Tokenmon 같은 downstream이 사용자의 명시적 동의와 선택 아래 local custom pet을 안전하게 소비할 producer 계약이 필요했습니다.
• 무엇: bounded reader/catalog, v2 schema/runtime/type, CLI key/TTY selector, experimental module subpath, human redaction과 downstream 보안 문서를 추가했습니다.
• 리뷰 포인트: Full Profile v1/root SDK 무변경, no-implicit-fallback 선택 우선순위, base64 image의 검증·재호스팅 경계를 먼저 확인해 주세요.

변경 내역

• Stage 1 (5c8e5b3): selected custom pet bounded reader와 path/image negative fixture를 구현했습니다.
• Stage 2 (89724cb): v1을 byte 단위로 보존하며 required pet을 가진 Full Profile v2 schema/runtime/type을 추가했습니다.
• Stage 2.5 (de193a2): privacy-safe catalog, explicit numeric key와 no-implicit-fallback 계약을 구현했습니다.
• Stage 3 (6674607): CLI/client/TTY selector/human output/experimental subpath/package/공식 문서를 통합했습니다.
• Stage 4 (a669fd8): 실제 v1/v2와 explicit-key image 무결성을 sanitized 검증하고 Tokenmon 인계 체크리스트를 확정했습니다.

영향 영역

영역	변경	리뷰 포인트
Local pet source	bounded state/manifest/PNG·WebP reader와 deterministic catalog	containment, symlink/size/dimension 제한, raw path/ID 비노출
Full Profile/CLI	opt-in v2, --pet-key, --select-pet, Desktop-default와 TTY fallback	v1 exact 보존, JSON no-prompt, root status/exit matrix
Package/downstream	experimental subpath, v2 schema와 decode/re-host/delete 지침	root export/dependency 불변, base64를 untrusted binary로 처리

작업 문서

• 수행 계획서: task_m04x_52.md
• 구현 계획서: task_m04x_52_impl.md
• 최종 보고서: task_m04x_52_report.md

핵심 리뷰 포인트

• includePet이 없으면 pet dependency를 호출하지 않고 Full Profile v1과 root SDK export를 그대로 유지합니다.
• 선택 우선순위는 explicit key → forced selector → Desktop selected → human TTY fallback이며, state가 불확실해도 첫/유일 pet을 암묵 선택하지 않습니다.
• v2 base64는 완전한 spritesheet bytes입니다. Downstream은 strict decode, byte/hash/dimension/full decode, safe re-encode/re-host와 별도 consent/delete를 적용해야 합니다.

검증

자동 검증

주제	검증 방법	결과	근거
전체 회귀	npm test	OK	178개 통과, fail/skip 0개
v1/v2 계약과 선택	schema/runtime/type/CLI/client/selector synthetic test	OK	v1 hash/field order, v2 status matrix, explicit/forced/Desktop/fallback과 no-implicit-fallback 확인
reader 방어	traversal/symlink/malformed/oversize/PNG·WebP fixture	OK	bounded allowlist success와 모든 unsafe source의 fixed unavailable 축약 확인
package surface	isolated-cache npm pack --dry-run --json과 exact export 검사	OK	28개 artifact, v2 schema/reader/selector/API 포함, test/fixture/mydocs 제외, root export 불변
정적 품질	privacy pattern, 문서 링크, 변경 범위, git diff --check	OK	사용자 경로/credential marker 없음, 상대 링크와 approved scope 통과

수동/시나리오 검증

시나리오	확인 절차	결과	자료
실제 opt-out profile	raw JSON을 출력하지 않고 v1 discriminator와 pet field 부재만 검사	OK	Stage 4 보고서
실제 Desktop-default v2	raw identity/base64 없이 root/pet status와 leakage boolean만 검사	OK	selected key 부재를 pet unavailable/root partial로 축약하고 암묵 fallback하지 않음
실제 explicit-key v2	catalog 이름/ID 없이 실제 WebP의 decoded length와 SHA-256을 envelope와 비교	OK	pet/root ok, bounds·byte length·digest 일치

CI/원격 검증

항목	결과	근거
원격 게시 브랜치	OK	publish/task52 신규 push 성공, 2026-07-19 확인
GitHub Actions test	OK	run 29674047380 / job 88157950394, 14초 통과

검증 한계

• Analyze (actions)와 Analyze (javascript-typescript) Check는 2026-07-19
  확인 시점에 진행 중입니다.
• Codex Desktop의 현재 state가 selected custom key를 제공하지 않아 실제 Desktop-default available 사례는 synthetic fixture로 검증했고, 실제 pet bytes는 explicit key end-to-end smoke로 검증했습니다.
• 실제 app-server smoke는 sandbox 밖의 로컬 실행 권한이 필요했습니다.

관련 이슈

• 없음

후속 이슈 제안

• 이 변경을 포함할 version bump/npm publish/release task
• analyzer merge/release 후 postmelee/tokenmon v2 consumer와 profile opt-in 구현 Issue
• 정적 portrait 또는 animation이 필요할 경우 spritesheet frame/layout consumer contract Issue

남은 리스크

• private profile endpoint와 Desktop local state는 upstream 안정성 계약이 없습니다.
• package metadata는 아직 0.4.0이며 이 PR은 publish를 수행하지 않습니다.
• Full Profile v2는 단일 portrait가 아닌 전체 spritesheet를 제공하며 frame/layout 의미는 범위 밖입니다.