JSON 주소와 값 검증을 Core 정본으로 통일한다

[developer-1px]

Goal Anchor

• Outcome: JSON 주소와 JSON 값의 공통 규칙을 Core 정본에서 소비하여 Rich Text·React·Zod·Clipboard 사이의 해석 불일치를 없앤다.
• Done: Core가 지원하는 주소로 만든 Rich Text editor가 React에서 같은 문서를 읽고 변경·관찰할 수 있다. JSON 값으로 수용한 clipboard/도메인 값이 Core의 JSON 제약과 일치한다. 영향 범위의 Pointer 인코딩과 일반 JSON 유효성 재구현을 제거하고 owner API·문서·Usage·source registration·회귀 검증을 갖춘다.
• Don't: JSONDocument의 여섯 멤버, 기존 JSON 유효성 규칙과 도메인 schema를 바꾸지 않는다. 읽기에 문서 전체 복제나 별도 mutable runtime을 도입하지 않는다. 단축키·Annotation·Gesture·기본 Profile 동결·PR merge는 이번 PR에 포함하지 않는다.

승인과 근거

사용자가 건강도 감사의 실행 우선순위에 대해 “진행하자”라고 요청했다. 이번 이슈는 첫 단계인 주소·JSON 검증의 정본화를 소유한다. 나머지 순서는 #725에 유지한다.

감사 기준 #730 ba1f0ee에서 공개 API로 확인했다.

• /editor: Rich Text editor 생성과 React SSR 성공.
• #/editor: editor 생성 성공, React SSR은 Rich Text document was not found로 실패.
• NaN, Infinity, Date, sparse array: Core applyPatch는 not_serializable, Sheet·Database clipboard parser는 수용.

책임과 영향 범위

• Core Pointer owner: 주소 문법·토큰 인코딩·대상 조회.
• Core JSON owner: 일반 JSON 값의 유효성. Sheet 직사각형, Database 형태, Rich Text schema 등 추가 조건은 도메인이 유지한다.
• Rich Text와 React: 정본 주소 해석을 소비하고 snapshot 참조 동일성·변경 관찰을 보존한다.
• Core JSONPath와 Zod: 기존 정본 Pointer 인코딩 API를 소비한다.
• Editing clipboard와 Rich Text: 같은 JSON 제약을 소비한다.
• 필요한 공개 capability는 기존 owner에서 최소한으로 노출하며, 패키지 README/API reference·site Usage·source registration을 연결한다.

완료 증거

1. root, 일반 Pointer, URI fragment, escaped key로 같은 문서를 읽고 Rich Text 편집 결과와 React 관찰이 일치한다.
2. 비유효 값·순환 구조·희소 배열 등을 도메인 입력에서 거절하고 유효한 JSON은 계속 수용한다. 거절 시 문서·선택·History를 바꾸지 않는다.
3. 영향 범위의 별도 Pointer encoder와 일반 JSON 판별 구현이 남지 않는다.
4. Core/Editing/Rich Text/React/Zod의 관련 테스트·타입 검사·빌드, 공개 계약·문서·site 등록 검사를 통과한다.

기존 작업과의 관계

• Cut 입력 소유권을 Web 정본으로 통합하고 실패 시 원본을 보존한다 #730 Cut 실패 처리는 독립 PR로 유지한다.
• refactor(annotation): 선택·gesture·출력의 정본 경계 통합 #589 Annotation 정리, Database saved-view와 편집 표현 책임을 정본화한다 #587 Database saved-view 정리는 기존 소유권을 유지한다.
• A2UI 상대 경로 의미와 History·Selection 종류의 통합은 이 이슈에서 결정하지 않는다.

[developer-1px]

Goal Anchor

• Outcome: JSON 주소와 JSON 값의 공통 규칙을 Core 정본에서 소비하여 Rich Text·React·Zod·Clipboard 사이의 해석 불일치를 없앤다.
• Done: Core가 지원하는 주소로 만든 Rich Text editor가 React에서 같은 문서를 읽고 변경·관찰할 수 있다. JSON 값으로 수용한 clipboard/도메인 값이 Core의 JSON 제약과 일치한다. 영향 범위의 Pointer 인코딩과 일반 JSON 유효성 재구현을 제거하고 owner API·문서·Usage·source registration·회귀 검증을 갖춘다.
• Don't: JSONDocument의 여섯 멤버, 기존 JSON 유효성 규칙과 도메인 schema를 바꾸지 않는다. 읽기에 문서 전체 복제나 별도 mutable runtime을 도입하지 않는다. 단축키·Annotation·Gesture·기본 Profile 동결·PR merge는 이번 PR에 포함하지 않는다.

작업 계획

주소·값 정본화
├─ 기존 실패를 공개 API 회귀 사례로 고정
├─ Core owner의 조회·검증을 소비 가능한 형태로 연결
│  ├─ Rich Text/React snapshot 조회와 변경 관찰
│  ├─ JSONPath/Zod Pointer 생성
│  └─ Clipboard/Rich Text 일반 JSON 검증
└─ owner 문서·Usage/source 등록 → 관련 검증 → PR

현재 main은 aae30a66이다. 원래 사용자의 dirty checkout과 #730 작업 폴더를 보존하고 새 issue worktree를 사용한다. #730의 Cut 수정은 이 변경의 선행 의존성이 아니다.

읽기 소비자가 정본을 쓰기 위해 매번 createJSONDocument(snapshot)로 전체 값을 복제하면 참조 동일성과 렌더 비용이 달라진다. 기존 Core 주소 조회를 값에 직접 적용하는 stateless capability로 연결하고, 일반 JSON 검증도 기존 validator를 재사용한다. 여섯 멤버의 document 계약과 도메인별 schema는 그대로 유지한다.

검증은 실패했던 URI fragment의 렌더·편집·관찰, 잘못된 clipboard 값의 거절과 상태 보존, escaped Pointer 생성, 기존 locality 테스트, 영향 패키지 verify, 공개 계약·문서·Usage/source 등록 검사 순서로 진행한다. 실제 브라우저 검증은 기존 Chrome 연결을 우선 확인한다.

미해결 Done은 위 사례의 수정과 검증이다. 단축키·Annotation·Gesture·전체 Profile 적합성 확대는 #725의 다음 단계로 남아 있다.

[developer-1px]

구현과 검증을 마쳤다. 남은 단계는 커밋·push·PR 등록이다.

확인한 완료 증거

• URI fragment와 # root의 Rich Text React 렌더 실패를 수정 전 테스트에서 재현했고, 수정 후 통과했다.
• 중첩·escaped 주소의 편집, Undo/Redo, 외부 변경 관찰이 같은 대상을 사용한다. 변경하지 않은 블록 참조와 incremental render 경로를 유지한다.
• Sheet·Database parser와 직접 Paste, Rich Text extension attrs·Paste가 비유효 JSON을 정규화 전에 거절한다. 거절 시 문서·선택·Redo와 알림을 보존하는 테스트가 통과했다.
• JSONPath·Zod의 독립 Pointer encoder, React의 수동 주소 해석, Clipboard/Rich Text의 별도 일반 JSON 판별을 제거했다.
• Core owner README, 생성 API reference, public API/llms, binding 계약, 실행 Usage와 source registration을 연결했다.

이전
├─ Core: Pointer 읽기·인코딩 / JSON 제약
├─ React: 자체 Pointer 해석
├─ JSONPath·Zod: 자체 Pointer 인코딩
└─ Clipboard·Rich Text: 자체 JSON 판별

이후
├─ readPointer → document.at / Rich Text snapshot / React
├─ buildPointer·appendSegment → JSONPath / Zod
└─ isJSONValue → Clipboard / Rich Text / site Usage

최소성 판단
새 document member나 domain 명령은 추가하지 않았다. 이미 존재하는 책임을 소비할 수 있도록 readPointer, isJSONValue라는 stateless binding 두 개를 공개했다. TypeScript root 허용 목록은 23→25 symbol이 되며, document의 여섯 멤버와 JSON 규칙은 유지한다. 공개 surface가 늘어난 사실을 숨기지 않고 binding 문서와 검증에 반영했다.

createJSONDocument(snapshot).at(...)로 정본을 소비하면 snapshot 전체 복제가 발생한다. 이번 연결은 그 복제 경로를 제거하고 원본 참조를 읽는다. 패키지 production source는 새 owner 파일까지 포함해 순증 8줄이며, 목적은 독립 알고리즘 수와 동작 불일치를 줄이는 것이다.

실행 검증

• Core: 365 통과, 기존 4 skipped. layer/typecheck/build 및 실제 tarball smoke 통과.
• Editing: 296 통과. Zod: 8 통과. Rich Text: 110 통과. Rich Text React: 31 통과. 각 패키지 typecheck/build 통과.
• Site: 25 files / 139 tests 통과. 전체 typecheck와 canonical/UI guard 통과.
• workspace:check, docs:evaluate, docs:api:check, standard:check 통과.
• site:verify:pages: build, 정적 검사, HTTP 검사 통과.
• git diff --check 통과. 원래 dirty checkout과 Cut 입력 소유권을 Web 정본으로 통합하고 실패 시 원본을 보존한다 #730 작업은 보존했다.

검증 한계
기존 Google Chrome에서 새 검증 탭을 열었으나 AppleScript JavaScript 실행이 차단되어 실제 Chrome 조작 검증은 미확인이다. 설정 변경이나 임시 profile 생성은 하지 않았다. URI fragment·변경 관찰은 SSR/jsdom 회귀 테스트로, Usage 동작과 source 공개는 site 테스트로 검증했다.

단축키·Annotation·Gesture·전체 Profile 적합성 확대는 이번 Done으로 표시하지 않는다. 기존 #725의 다음 단계이며 Annotation Host 정리는 #589가 이미 소유한다.

[developer-1px]

PR #732를 열었다: #732

• 상태: pr-open
• 커밋: a4fa60d2
• branch: issue-731-canonical-json-primitives
• remote PR head와 local HEAD, 변경 파일 44개가 일치하고 Closes #731 연결을 확인했다.
• 주소 조회·JSON 검증 정본화, 소비자 연결, owner 문서·Usage/source 등록과 회귀 검증을 완료했다. 상세 결과는 앞의 검증 댓글에 있다.
• Chrome의 AppleScript JavaScript 실행 차단으로 실제 Chrome 조작은 미확인이다. SSR/jsdom·site Usage 테스트와 site build/HTTP 검증은 통과했다.
• merge는 수행하지 않았다. 단축키·Annotation·Gesture·전체 Profile 적합성 확대는 이 PR의 완료 범위에 포함하지 않는다.

[developer-1px]

CI 후속 확인: Package·External kit은 통과했고, Site browser 232개 통과·4개 skip 중 소스 탭 목록 1개가 실패했다. Database가 Core isJSONValue를 소비하면서 source closure에 serializable.ts가 추가되었는데 browser 기대 목록에 반영하지 않은 원인이었다.

#731 Done의 source registration 검증에 해당하는 누락을 dd39608a에서 수정했다. 해당 source closure 단위 테스트 16개와 git diff --check는 통과했다. 기존 Chrome 자동 제어 제한 때문에 로컬 browser 통과로 대체 보고하지 않으며, 수정 head의 CI 결과로 다시 확인한다.

[developer-1px]

후속 head dd39608a에서 CI Plan·Package·Site·External kit이 모두 통과했다. source closure의 browser 기대값 누락이 해소되었다. PR #732는 열린 상태로 유지한다.

[developer-1px]

사용자가 PR #732를 먼저 병합하고 core 주변 경량화를 계속 진행하도록 승인했다. 현재 head dd39608a의 CI Plan·Package·Site·External kit은 모두 통과했지만 최신 main과 충돌한다. 기존 dirty checkout은 변경하지 않고 별도 작업 공간에서 충돌을 해결하고 영향 검증을 다시 실행한 뒤 병합한다. 주소·JSON 값의 정본화라는 기존 계약은 유지한다.

[developer-1px]

최신 main 병합 충돌은 demo-sources.ts의 import 한 곳이었다. Core readPointer/isJSONValue와 Selection key 등록을 모두 보존했다. head eb5dd6b4에서 root build, 전체 155 files / 1,517 tests 통과(기존 4 skipped), site typecheck와 모든 UI/canonical guard, docs:evaluate, docs:api:check, workspace:check, git diff --check를 확인했다. 최초 테스트는 build 완료 전에 실행해 의존 package dist를 찾지 못했으나, build 완료 후 전체 suite를 다시 실행해 통과했다. 원래 dirty checkout은 그대로 보존했다. 사용자 승인에 따라 별도 강제 우회 없이 병합한다.