@hatiolab/figure-model 0.1.30 → 0.1.31

package/docs/v3-spatial-contracts.md

@@ -0,0 +1,84 @@
+# V3 타입·공간 그래프 통합 실험
+
+> 현재 구현·검증·제품 연결 상태는 [V3 통합 현황](v3-status.md)을 따른다. 본문의 단계별 연구/검증 기록은 제품 전체 완료 선언이 아니다.
+
+후속: [드라이룸 실제 단면·메시 검증](v3-dryroom-profile-validation.md).
+
+상태: r3의 일부 계약 구현. 제품 런타임/정식 schema/전체 자산 변환이 아니다.
+[숫자 타입 계약](v3-operator-contracts.md)의 동일 `compile/evaluate` 실행기를 확장했다.
+기존 무단위 v3-kernel을 따로 호출하거나 좌표를 두 번 계산하지 않는다.
+
+## 1. 타입
+
+- scalar: 길이·각도·시간의 차원 지수.
+- point<F>: F 좌표계의 점.
+- transform<From,To>: From 좌표를 To 좌표로 옮기는 SE(3) 변환.
+- shape<Provider,F>: F 로컬 좌표에서 정의된 geometry descriptor.
+- placed<F>: F 좌표계로 배치한 shape와 pose.
+
+좌표계 이름은 현재 선언자의 nominal label이다. 타입이 동일하다는 것은 같은 label을
+사용했다는 뜻이다. 외부 자산 namespace, label 소유권, entity당 canonical world pose의
+유일성을 완전히 검증하는 기능은 아직 없다. 고의로 잘못 붙인 label의 의미를 추론하지 않는다.
+방향 벡터 타입은 이번에 구현하지 않았다. point와 transform부터 통합했다.
+
+## 2. 연산
+
+| 연산 | 입력 → 출력 | 검사 |
+| --- | --- | --- |
+| rigid@1 | 길이3·각도3 → transform<from,to> | mm/rad 타입, 유한값 |
+| compose@1 | A<B,C>, B<A,B> → transform<A,C> | 중간 좌표계 일치 |
+| attach@1 | A, O, B → A·O·inverse(B) | 대상·자기 feature 좌표계 호환 |
+| point@1 | 길이3 → point<F> | 선언 frame |
+| map-point@1 | transform<A,B>, point<A> → point<B> | source frame 일치 |
+| distance@1 | point<F> 두 개 → 길이 | 같은 frame |
+| box-shape@1 | 길이3 → shape<box,F> | 양의 치수 |
+| cylinder-shape@1 | 반지름·길이 → shape<cylinder,F> | 양의 치수 |
+| feature@1 | shape → feature-local에서 shape-local로의 transform | provider가 지원하는 feature 이름 |
+| place@1 | shape<F>, transform<F,G> → placed<G> | shape-local과 pose source 일치 |
+
+rigid 회전은 rad, 열벡터, R=Rx·Ry·Rz로 정의한다. translation은 결과 좌표계에서 표현한다.
+외부 행렬을 직접 받아 역행렬을 추정하지 않는다. rotation은 삼각함수로 구성한 rigid matrix이며
+역변환은 Rᵀ 및 −Rᵀt를 쓴다. 변환 연쇄의 오차 보수 경계는 아직 없다.
+
+box feature: left/right/bottom/top/back/front.
+cylinder feature: Y축 start/end, local −Z 방향의 radialBottom.
+radialBottom은 임의 방향 접촉 탐색이 아니라 **정해진 단면 점**이다.
+feature의 축은 provider 축과 평행하다. 표면 바깥 법선을 향한 frame이 아니므로
+일반 면 mating에서 필요한 방향은 명시 offset에 넣어야 한다.
+
+geometry 치수에서 feature를 계산하고, 그 feature가 pose 입력이 된다.
+placement가 만든 world point 사이 거리를 다른 geometry의 길이로 사용할 수도 있다.
+따라서 고정된 '모든 숫자→모든 형상→모든 배치' 순서를 강제하지 않고 전체 port graph를 정렬한다.
+
+## 3. 실행 검증
+
+```sh
+node --test docs/prototypes/v3-spatial-plan.test.mjs docs/prototypes/v3-typed-plan.test.mjs
+```
+
+통합 공간 검사 7개 + 기존 scalar 검사 9개 통과.
+
+- 바퀴 접지 의도: 5반지름×5바닥 높이×5방향=125조합. 접점 Y=바닥,
+  중심 Y=바닥+반지름, geometry 반지름 일치.
+- 지지부·램프: 4높이×3³ XYZ 회전=108조합. 자기 하단과 대상 상단의 world frame 일치.
+- 관절 연결: 3높이×5관절각=15조합. 위치 결합 유지, 자세 변화.
+- world point 간 거리로 cylinder 길이 생성. local/world 혼용 시 거절.
+- 잘못된 compose 순서, 자기 feature frame 불일치, shape/pose frame 불일치,
+  transform을 scalar 덧셈에 넣는 경우 거절.
+- geometry→feature→pose→point→거리→원래 geometry의 cycle을 한 그래프에서 검출.
+- 알 수 없는 feature 거절, 선언 역순 결과 유지, 실패 후 재평가에서 stale 값 없음.
+
+이 시험은 실제 seed 전체를 읽는 변환 시험이 아니다. 바퀴·부착·관절이라는 대표 의도를
+최소 선언으로 검사했다. '지지부'는 box이며 드라이룸 U자 polygon이나 robot-arm 전체가 아니다.
+메시 생성·렌더러 연결·시각 검사·충돌 검사도 하지 않았다.
+
+## 4. 다음 통합 과제
+
+1. frame 이름의 자산별 namespace와 canonical pose 소유권 계약.
+2. point뿐 아니라 direction/normal/tangent와 feature 종류의 타입.
+3. 비대칭 profile provider: 드라이룸 opening/top/bottom을 실제 단면에서 계산.
+4. typed topology/반복을 이 그래프에 통합하고 삭제 참조 정책 적용.
+5. 실제 자산 전체를 변환해 mesh/시각 결과 및 예산 측정.
+
+지금 통합한 것의 가치는 '한 엔진에 숫자와 좌표계 의존성이 함께 들어왔다'는 데 있다.
+이 상태를 전체 V3 완성으로 해석하지 않는다.

package/docs/v3-status.md

@@ -0,0 +1,41 @@
+# V3 구현·검증 현황
+
+기준일: 2026-09-21. **현재 상태를 판단하는 문서다.** 개별 연구·검증 문서의 과거 단계 수치나 '다음 단계'보다 이 현황을 우선한다.
+
+## 제품 방향
+
+모델러·AI·저장·렌더러를 **V3 하나로 전환**한다. V2 호환성·병행 운영은 요구사항이 아니다. 기존 자산은 V3로 변환하거나 재작성한다. 원본 복구본은 데이터 교체를 위한 안전 조치일 뿐 V2 실행 지원을 뜻하지 않는다. [전환 결정](v3-cutover.md)
+
+## 완료 범위와 미완료 범위
+
+| 영역 | 현재 구현 | 남은 작업 |
+|---|---|---|
+| 입력·그래프 | src의 JSON 검사, 단위·좌표계·형상·반복 평가 | 내부 Dynamic 경계 축소, 전체 수치/자원 한계 검증 |
+| capability | 선언·표면 소유권·반복 참조·수용 조건 검사 | 일반적 접촉·충돌·물리 안전성 보장 |
+| 자산 | JSON 읽기/쓰기, 재질·팔레트·기본값 복원 | 실제 자산 전체 전환, 범용 공급자/재질 확장 |
+| 저작 | 빈 자산, 명시적 상자 추가, 크기·위치·회전 입력 | 다른 primitive 추가, 삭제·재질·관계 편집 |
+| 편집 상태 | UI/AI 공통 입력 검증, 구조/입력 통합 50단계 undo/redo, context/revision 검사 | 실제 AI 명령 해석·승인·대화 이력 연결 |
+| 저장 | export/저장 확인 분리, 격리 HTTP 파일 저장·복원·충돌 테스트 | 인증·제품 DB CAS·재시도·발행/목록 통합 |
+| 화면 | 격리 Three.js UI의 생성·추가·편집·undo/redo·파일 저장·복원 | 제품 모델러·렌더러·AI-dock 연결과 배포 |
+
+**제품 서버 localhost:3300의 V3 전환·배포는 아직 완료하지 않았다.** 격리 UI의 성공을 제품 배포 완료로 보고하지 않는다. 최신 구현은 패키지 소스에 있으며 설치된 제품 패키지 반영은 별도 확인이 필요하다.
+
+## 검증 근거
+
+- `npm test`: 소스 **455개 통과**. 기존 검사와 신규 V3 검사를 합친 수치이며 V3 기능 수가 아니다.
+- `node --test docs/prototypes/v3-*.test.mjs`: 실험 **143개 통과**.
+- `npm run build`: 타입 선언·JS 생성 성공.
+- `node docs/prototypes/v3-runtime-browser.mjs`: Chrome에서 빌드된 모듈 실행, 네 대표 모델(드라이룸·컨베이어·로봇암·포크리프트)의 계산값/형상/재질/binding을 Node와 비교.
+- `node docs/prototypes/v3-editor-browser.mjs`: 빈 자산 → 상자 추가 → 속성 수정 → 수정 취소 → 생성 취소 → 재실행 → 파일 저장/복원. 기존 모델 전환 후 잔여 메시 제거도 확인. page error0개, 캔버스 직접 확인.
+
+브라우저 검증 도구는 로컬 Chrome·Playwright·Three.js 경로를 사용하는 개발 도구다. 운영 배포 도구가 아니다. 파일 저장 테스트는 전용 임시 데이터를 생성하고 종료 후 정리한다.
+
+## 구현을 읽는 순서
+
+1. [최소 의미 계약](v3-core-semantics.md) — 설계 방향, 구현 완료 선언 아님.
+2. [정식 소스 이관 기록](v3-runtime-extraction.md) — 단계별 구현/검증 이력.
+3. [편집 계약](v3-authoring-transactions.md), [편집 화면](v3-editor-integration.md).
+4. [자산 계약](v3-asset-persistence.md), [저장 검증](v3-storage-integration.md).
+5. [V3 단일 전환](v3-cutover.md).
+
+다음 작업은 모델러의 사용자 동작·AI·실제 저장·렌더링을 이 공용 V3 구현에 연결하는 것이다. 완료한 계층을 다시 이관하거나 V2 호환 분기를 추가하는 것이 아니다.

package/docs/v3-storage-integration.md

@@ -0,0 +1,58 @@
+# V3 저장 API 경계와 파일 영속화 검증
+
+> 현재 구현·검증·제품 연결 상태는 [V3 통합 현황](v3-status.md)을 따른다. 본문의 단계별 연구/검증 기록은 제품 전체 완료 선언이 아니다.
+
+## 이번 단계의 결과
+
+격리 편집 화면의 메모리 저장을 **HTTP 요청 → 의미 검증 → 파일 저장 → 저장 확인**으로 변경했다. 저장한 자산은 파일에서 다시 열며, 별도 Node 프로세스에서도 복원한다. 실제 제품의 GraphQL API·DB·기존 자산은 변경하지 않았다.
+
+- [파일 저장소](prototypes/v3-asset-store.mjs)
+- [저장·충돌·별도 프로세스 복원 테스트](prototypes/v3-asset-store.test.mjs)
+- [브라우저 연결](prototypes/v3-editor-browser.mjs)
+
+## 왜 기존 저장 API에 바로 연결하지 않았는가
+
+제품 figure-service의 `figure-source.ts`는 V2 validate/compile/costOf/scoreOf를 호출한다. `figure-mutation.ts`의 생성·수정·되돌리기는 이 검증을 사용하며 발행은 V2 검사 경로를 사용한다. figure-ui도 draft/parts를 직접 편집한다.
+
+실험 포맷만 허용하면 저장은 되지만 기존 소비자가 읽을 수 없는 자산이 된다. 따라서 **제품 V3 경로 연결은 아직 미완료**다. 실험 코드의 직접 import, package.json 변경, V2 검증 우회는 하지 않았다.
+
+## 저장 계약
+
+`save({scope,id,expectedRevision,text})`에서 scope/id는 저장 대상, expectedRevision은 저장소 revision이다. 새 자산은 null을 명시한다. 편집 세션의 숫자 revision이나 발행 판 번호와 섞지 않는다.
+
+1. 서버에서 자산 형식과 의미를 검증하고 정규화한다.
+2. 해당 저장 대상의 현재 revision과 요청 revision을 비교한다.
+3. 다르면 CONFLICT로 거부한다. 마지막 저장자가 무조건 이기는 정책을 사용하지 않는다.
+4. 임시 파일에 쓰고 fsync한 뒤 같은 디렉터리에서 rename한다.
+5. 매 저장마다 새 UUID revision을 반환한다. 내용이 A→B→A로 돌아와도 옛 revision으로 덮어쓸 수 없다.
+6. 편집 화면은 실제 저장 성공 후에만 저장 완료를 확인한다. 저장 도중 모델이나 편집 revision이 바뀌면 이전 응답으로 현재 편집을 저장 완료 처리하지 않는다.
+
+scope/id 조합을 해시한 파일명으로 사용해 사용자 식별자를 경로로 해석하지 않는다. **이것은 권한 검증이 아니다.** 제품에서는 인증된 서버 context에서 domain을 결정하고 조회·쓰기 권한을 별도로 검사해야 한다.
+
+## 검증
+
+- 파일 저장 후 새로운 저장소 핸들로 동일 자산 복원.
+- 별도 Node 프로세스에서 포크 길이1275mm와 저장 revision 복원.
+- 동일 revision 동시 저장 두 건 중 한 건만 성공.
+- scope가 다른 자산 조회 차단(NOT_FOUND), 생성 중복 및 누락 precondition 거부.
+- 잘못된 V3 자산 저장 시 기존 파일 보존.
+- 충돌 시 화면의 변경값과 미저장 상태 보존.
+- Chrome에서 HTTP 파일 저장, 로봇 전환, 파일 복원, 빈 캔버스 초기화 확인. page error 0개.
+
+테스트가 생성한 전용 임시 디렉터리만 종료 시 제거한다. 사용자의 모델이나 제품 DB는 다루지 않는다.
+
+## 운영 환경에 적용할 수 없는 제한
+
+- 파일별 직렬화 큐는 **단일 프로세스**에서만 동작한다. 여러 서버 프로세스에서는 DB의 원자적 조건부 갱신/CAS가 필요하다.
+- 파일 내용을 fsync하지만 디렉터리 fsync 및 전원 장애 복구를 검증하지 않았다. 완전한 장애 내구성을 보장하지 않는다.
+- 브라우저 실험은 인증 없는 loopback 전용 테스트다. 운영 API가 아니다.
+- 삭제/복구, 발행 이력, 목록/검색, 감사 이력, 저장 재시도 idempotency는 아직 구현하지 않았다.
+
+## 제품 연결 순서
+
+1. 입력·그래프·capability·문서·자산·편집 workspace의 정식 소스 이관은 [완료](v3-runtime-extraction.md)했다. 이 모듈들을 제품에 반영한다.
+2. figure-service의 저장·조회·발행을 V3 단일 기준으로 전환하고 저장 revision CAS를 구현한다. V2 병행 운영은 요구사항이 아니다.
+3. figure-ui와 렌더러·AI를 V3 단일 경로에 연결한다. 기존 자산은 V3로 변환하거나 재작성한다.
+4. 실제 인증·DB로 두 편집 세션의 충돌, 저장 실패, 재접속, 모델 전환, AI 늦은 응답을 검증한다.
+
+이 문서의 완료 범위는 저장 경계의 실행 가능한 검증이며, 제품 연결·배포 완료가 아니다.

package/docs/v3-typed-repeat-contracts.md

@@ -0,0 +1,79 @@
+# 반복 조립체의 typed graph 통합
+
+> 현재 구현·검증·제품 연결 상태는 [V3 통합 현황](v3-status.md)을 따른다. 본문의 단계별 연구/검증 기록은 제품 전체 완료 선언이 아니다.
+
+상태: 독립 실험. 제품 런타임·원본 시드·DB 변경 없음.
+기존 `v3-typed-plan.mjs`의 compile/evaluate와 동일한 타입/참조/순환 검사 경로를 사용한다.
+예전 무단위 pattern expander를 호출하지 않는다.
+
+## 구현 계약
+
+- count는 무차원 ratio와 구별되는 타입이며 0 이상의 safe integer만 허용한다.
+- fit-pitch@1은 L,a,b,항목 외곽 길이 e,pitch,정렬 비율,최대 개수로 layout을 생성한다.
+  `n = usable<e ? 0 : 1+floor((usable-e)/pitch)`이며 실제 e와 양끝 여백을 반영한다.
+- fixed-count@1은 개수를 고정하고 양끝 여백 안에서 등간격으로 배치한다.
+  2개 이상은 첫/끝 항목을 양끝에 맞추고, 1개일 때 정렬 비율을 사용한다.
+  이 연산 버전은 비겹침을 요구한다. 공간 부족을 자동 축소로 숨기지 않는다.
+- member@1은 렌더링되지 않는 placed 값이다. assembly@1은 같은 좌표계의 member들을 묶는다.
+  템플릿이 반복 결과와 별도로 한 번 더 그려지는 것을 막는다.
+- repeat@1은 layout→항목 위치→member 내부 pose 순서로 합성한다.
+  출력은 collection과 최종 geometry 목록이다. collection도 다른 연산의 typed 입력이다.
+- select-item@1은 collection에서 index와 member key를 선택한다.
+  없으면 TARGET_ABSENT. 현재는 필수 참조만 구현했고 optional 참조는 미구현이다.
+- input의 role=state 의존성을 그래프에 전파한다. layout이 직접/간접 state에 의존하면
+  TOPOLOGY_STATE로 거절한다. role을 생략하면 design이다.
+
+id는 `[repeat node id, ordinal index, member output port id]`다.
+멤버 배열 순서 대신 이름을 사용하지만 port 이름을 변경하는 정식 rename transaction은 아직 없다.
+같은 id가 유지돼도 기준 위치가 움직이면 world 위치는 달라질 수 있다.
+직렬화 키가 영속 외부 시스템에 안전하게 이행되는지는 아직 검증하지 않았다.
+
+## 실행 사례와 명시한 의도
+
+실제 seed에서 형상 치수·pitch·상대 좌표를 읽되, 전체 모델의 자동 변환은 아니다.
+
+| 사례 | 사용한 부분 | 이번 배치 의도 | 기준 크기 geometry 수 |
+| --- | --- | --- | ---: |
+| 화성 트레이 | cell/contact | 8쌍 고정, 양끝 30mm, 셀 폭 52mm, 내부 Y차 90mm | 16 |
+| 충방전기 | shelf/channel-lamp | 양끝160mm, 묶음 외곽60mm, pitch400mm | 14 |
+| 컨베이어 | roller | 양끝150mm, 외곽96mm, pitch150mm, 개별 회전 | 14 |
+
+컨베이어 여백150mm는 양끝 롤러 공간을 남기는 **새 명시 의도**다.
+끝 롤러를 이번 geometry 집합에 넣거나 서로의 충돌을 전수 검사하지 않았다.
+원본 2400mm에서 16개였던 반복을 그대로 보존한다고 주장하지 않는다.
+
+트레이의 고정 개수 연산은 남은 폭에 균등 배치한다. 600mm에서 중심 간격은
+`(600−60−52)/7 ≈ 69.714mm`로, 원본 pitch68mm와 다르다.
+이는 원본 보존 성공이 아니라 새로운 관계의 명확한 의미를 시험한 것이다.
+원본 pitch를 유지하려면 고정 개수+고정 pitch의 다른 명시 연산이 필요하다.
+
+트레이와 선반의 rect는 box proxy다. round/material/emissive는 미검증이다.
+멤버 간 관계는 이번 adapter에서 원본 상대 pose로 구성했다.
+같은 graph의 feature 연산을 연결할 수 있지만 이 검사가 모든 멤버의 feature 부착을 검사한 것은 아니다.
+
+## 검사 결과
+
+```sh
+node --test docs/prototypes/v3-typed-repeat.test.mjs
+```
+
+5개 검사 통과:
+
+1. 3종×3길이×5각도=45입력 조합. 쌍의 대응·경계 여유·출력 수 검사.
+   회전 상태가 실제 동작을 바꾸는 것은 컨베이어이며 나머지 두 사례의 angle은 사용되지 않는다.
+2. 컨베이어 395/396/545.99/546/546.01mm 경계에서 0/1/1/2/2개.
+   빈 결과 허용, 최대 개수 초과·고정8셀 공간 부족 거절.
+3. 축소/확대/재평가의 id 유지와 필수 참조 소실 거절.
+4. ratio를 count로 전달, 소수 count, layout의 상태 의존, frame 불일치, 순환 거절.
+5. 기준 크기에서 메시44개 생성. welded edge pairing, Euler=2, 양의 face area/volume 확인.
+   생성 메시 검증이며 viewport 화면 확인이나 전체 장비 충돌 검사가 아니다.
+
+예산은 layout 최대10000, 확장 geometry 최대10000의 실험용 제한이다.
+이 값을 제품 권장 성능 한계로 해석하지 않는다. source graph의 총 자원 예산은 별도 보완 대상이다.
+floor 근처의 일반 실수 오차 정책도 미확정이다. 임의 epsilon/clamp를 넣지 않았다.
+
+## 다음 조건
+
+typed 반복과 단위·공간 계산 경로는 연결됐다. 다만 nested template, 항목별 상태,
+optional binding, template instance별 frame namespace, 실제 layout envelope 검증은 남아 있다.
+출하 전에는 profile/round/material을 포함한 전체 자산으로 확대해 렌더링과 성능을 검증해야 한다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hatiolab/figure-model",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "description": "Figure 저작 결과의 정본 형식과 검증 — 재질별로 병합되고 이름이 붙은 부품 그래프. 3D 로 저작한 형상 하나가 씬 컴포넌트로 서는 데 필요한 것을 담는다.",
   "keywords": [
     "figure",