@hatiolab/figure-model 0.1.30 → 0.1.31

package/docs/v3-research-review.md

@@ -0,0 +1,160 @@
+# Figure v3 선행 연구 검토와 채택 판단
+
+> 현재 구현·검증·제품 연결 상태는 [V3 통합 현황](v3-status.md)을 따른다. 본문의 단계별 연구/검증 기록은 제품 전체 완료 선언이 아니다.
+
+2026-09-20 · 1차 원문/공식 문서 검토.
+**문헌 검토이며 재현 실험 완료가 아니다. r1/r2도 아직 채택하지 않는다.**
+
+후속 진행: [ShapeAssembly 공개 interpreter의 10개 격리 실행 기록](v3-shapeassembly-reproduction.md).
+이 문서의 문헌 기반 비교와 실제 실행 결과를 구분한다. 논문 benchmark 재현은 아직 아니다.
+
+## 1. 결론
+
+현재 확인한 자료에서 Figure 요구 전체에 대해 “완벽에 가까운 해결”이 검증된 단일 연구는 찾지 못했다.
+이것은 그런 연구가 전혀 없다는 뜻이 아니다. 평가 범위가 다른 연구를 만능 해법으로 해석하지 않는다.
+
+우선 비교 대상은 ShapeAssembly/ShapeMOD 계열의 작은 구조 언어, CGA의 절차적 분할,
+기하 제약 해결 방식이다. OpenUSD는 좌표/변환 참조 명세이지 경쟁하는 자동 배치 알고리즘이 아니다.
+iWIRES는 이미 만들어진 mesh에서 설계 관계를 복원하는 별도의 비교 대상이다.
+
+핵심 판단: **실행에 필요한 자유도와 사용자가 조절하는 자유도를 구별하되,
+둘 사이를 검증 가능한 관계로 묶는다.** 프로그램을 짧게 만드는 것만으로 충분하지 않다.
+이 판단은 연구를 Figure에 적용한 우리의 해석이며 논문의 보장 사항이 아니다.
+
+## 2. '좋은 평가'를 판단하는 기준
+
+- 동료 심사 논문 게재: 연구 기여가 검토됐다는 근거. 제품 완전성 인증은 아님.
+- 비교 실험: 어떤 데이터·평가 기준·baseline에서 나아졌는지 확인.
+- 사용자 실험: 참가자의 배경, 작업 범위, 자유로운 편집인지 제한된 파라미터 조절인지 확인.
+- 후속 연구: 후속 방식이 무엇을 개선했는지 확인. 후속 논문이 있다는 사실만으로 재현 성공은 아님.
+- 공개 구현: 재현 가능성을 높이지만 코드 품질·라이선스·현행 환경 호환성은 별도 확인.
+- Figure 적합성: 실제 접촉, 곡면/구멍, 운동, 반복, 저작 난이도, 대량 렌더링은 따로 측정.
+
+이번 조사에서는 관련 연구의 논문 자체에 대한 Best Paper 수상이나 독립 재현 인증을 확인하지 못했다.
+연구자 개인의 수상, 다른 논문의 수상, 저장소 star를 해당 논문의 완전성 근거로 쓰지 않는다.
+인용 수는 출처/시점이 일관된 값으로 확인하지 않았으므로 순위 근거에서 제외한다.
+
+## 3. 확인한 근거와 한계
+
+### ShapeAssembly — SIGGRAPH Asia 2020 / ACM TOG
+
+작은 부품 생성·부착 언어와 파생 매크로, 생성 모델을 함께 제안한다.
+Figure가 비교할 부분은 전체 학습 모델보다 구조 표현과 실행 의미다.
+공식 프로젝트에 코드가 공개되어 있다.
+[프로젝트](https://rkjones4.github.io/shapeAssembly.html)
+
+논문 §8/부록 C–E를 확인했다. 데이터에서 유효 프로그램으로 변환된 비율은
+Chair 46%, Table 65%, Storage 58%다. 이는 생성 성공률이 아니라 **데이터 추출률**이다.
+논문은 계층 내부가 연결돼도 최종 leaf 부품 연결은 보장되지 않는다고 명시한다.
+rootedness 측정은 두 부품 간 거리가 전체 bbox 대각선의 2% 이내이면 연결로 간주한다.
+따라서 높은 연결 점수가 실제 접촉 보존의 증명은 아니다.
+[논문](https://rkjones4.github.io/pdf/shapeAssembly.pdf)
+
+**판정:** 최소 구조 언어의 중요한 비교 기준. Figure 실행 형식으로 그대로 채택하지 않는다.
+실제 면/개구부/곡면과 관절 계약은 별도 검증이 필요하다.
+
+### ShapeMOD — SIGGRAPH 2021 / ACM TOG
+
+공통 구조를 묶어 불필요한 조절값을 줄이는 연구다.
+저자 보고에 따르면 매크로가 생성·추론·편집 결과를 개선한다.
+작은 언어만 주장하는 것보다 사용자 조절 자유도의 근거를 제공한다.
+[프로젝트](https://rkjones4.github.io/shapeMOD.html)
+
+§6.4의 실험은 프로그래밍 경험이 있는 대학생 38명, 가구 3종의 6개 작업,
+작업당 10분이다. 목표는 같은 프로그램 구조의 연속 파라미터를 바꿔 도달할 수 있도록 선정됐다.
+자유로운 구조 저작이나 산업 설비 사용자 실험은 아니다. 저자는 모든 작업에서
+매크로 조건의 목표 수렴이 더 빨랐다고 보고한다.
+[논문](https://rkjones4.github.io/pdf/shapeMOD.pdf)
+[NSF 원문 보관본/검색 가능한 본문](https://par.nsf.gov/servlets/purl/10289210)
+
+**판정:** 사용성 단순화의 우선 참고 연구. 전체 학습 기반 매크로 발견기를 도입하기 전에,
+수작업으로 검증한 소수 조작만으로 같은 효과를 얻는지 비교한다.
+
+### ShapeCoder — SIGGRAPH 2023 / ACM TOG
+
+후속 연구는 더 약한 입력 가정 아래 구조적·파라미터 관계를 발견하며,
+프로그램 복잡성과 매크로 라이브러리 복잡성을 함께 줄이는 목적을 둔다.
+이는 기능을 묶는다는 이유로 매크로 종류를 무한히 늘리는 것도 해결책이 아니라는 근거다.
+[프로젝트](https://rkjones4.github.io/shapecoder.html)
+
+**판정:** 관계/템플릿 발견의 장기 참고. 현재 Figure runtime이나 즉시 적용 가능한
+최소 solver로 취급하지 않는다. 학습·추론 재현은 수행하지 않았다.
+
+### CGA / CityEngine
+
+공식 split 명세에는 고정·비례·남는 공간의 비율 배분·반복이 정의되어 있다.
+그러나 oversized 예제에서는 뒤쪽 형상이 잘리거나 생성되지 않는다.
+이 동작을 부품 보존이 필요한 Figure에 그대로 가져올 수 없다.
+[공식 split 명세](https://doc.arcgis.com/en/cityengine/latest/cga/cga-split.htm)
+
+**판정:** 절차적 분할의 비교 기준. 문법 전체가 아니라 치수 배분과 실패 정책을 분리해 검토한다.
+명세와 제품이 존재한다는 사실은 모든 산업 조립 의도를 보장한다는 뜻이 아니다.
+
+### SolveSpace / 기하 제약 방식
+
+공식 설명은 일반 기하 제약에 수정 Newton 방법을 사용하고,
+전방 대입 가능한 식 등은 별도로 처리한다고 설명한다.
+해가 여러 개이면 초기 위치가 선택되는 해에 영향을 준다.
+[공식 기술 설명](https://solvespace.com/tech.pl)
+
+**판정:** r2의 '모든 순환 거절'을 확정하기 전에 비교할 대상.
+선형 치수 문제와 비선형 기하/운동 문제를 하나의 solver 문제로 섞지 않는다.
+가능한 배치를 실패시키는 것과, 여러 해 중 사용자의 의도를 잘못 고르는 것 모두 실패로 측정한다.
+
+### iWIRES / 좌표계 명세
+
+iWIRES는 기존 형상에서 구조를 추출해 편집에 이용한다. 논문은 잘못 추출한 관계가
+과잉 제약을 만들 수 있다고 명시한다.
+[원문](https://www.cs.tau.ac.il/~dcor/articles/2009/iWIRES.pdf)
+
+OpenUSD의 Xformable은 변환 순서와 상속을 참고할 공식 계약이다.
+자동 치수 조절이나 조립 적합성을 해결하는 명세로 해석하지 않는다.
+[공식 문서](https://openusd.org/dev/api/class_usd_geom_xformable.html)
+
+**판정:** 전자는 기존 자산 관계 복원의 참고, 후자는 좌표/변환 계약의 참고.
+Figure의 사용자 의도나 resize 안전성을 대신 보장하지 않는다.
+
+## 4. 동일 사례에서의 적용성 비교 — 문헌 기반 예상, 실행 결과 아님
+
+| Figure 사례 | 작은 구조 언어 | 절차적 분할 | 기하 제약 |
+| --- | --- | --- | --- |
+| 문틀+두 문짝+고정 간격 | 부착·사이 채우기의 직접 사례 | 좌우 분할이 자연스러움 | 등식으로 표현 가능; 해 선택 필요 |
+| 실제 opening과 두께 유지 | 상자 대리 형상을 넘는 계약 필요 | 형상 생성 규칙과 치수 공유 필요 | 내부/외부 면 정의 필요 |
+| 곡면 롤러의 원형·길이 유지 | 별도 원형 파라미터가 필요 | 배분 공간과 geometry를 구별해야 함 | 반지름/축 관계 표현 후 수렴 검증 |
+| 회전 문에 붙은 손잡이 | 정적 구조와 운동을 연결해야 함 | 분할만으로 운동 상속은 해결 안 됨 | 관절·과잉 구속 검사 필요 |
+| 두 지지체 사이 부품 | 정해진 방향의 계산이 쉬움 | 영역을 먼저 정의해야 함 | 양방향 편집 가능성, 복수해 위험 |
+| 불규칙한 기존 polygon | 관계 추론/표면 대응 필요 | 원래 부품 의미 보존 확인 필요 | 기하 요소와 제약을 먼저 정의해야 함 |
+| 크기에 따른 부품 수 변경 | 생성 규칙·안정 id 필요 | 반복 연산과 가까움 | 연속 제약만으로 topology 변경 안 됨 |
+
+**어느 열도 완전한 승자가 아니다.** 기능을 모두 합치자는 결론도 아니다.
+우선순위는 문틀/램프의 부착 보존과 치수 유지이며, 위 표의 부족 항목을 실제 fixture로 검증한다.
+
+## 5. r2에 대한 조치
+
+- r2는 채택 보류. '아핀 DAG만', '배치 부모=운동 부모'는 아직 선택지다.
+- '작은 언어면 쉽다'를 철회. 편집 조작의 자유도와 사용자 작업 수를 측정한다.
+- '연결됨'은 점/면/기하학적 접촉/운동 중 유지 중 무엇인지 구분한다.
+- 내부 bbox의 연결을 실제 표면 접촉으로 대체하지 않는다.
+- authoring 중 제약 해결과 runtime의 결정된 결과 평가를 분리할 가능성을 검토한다.
+  이 분리는 유력한 가설이지 채택 확정이 아니다.
+- 검증된 기본 조작을 조합하되 Flex/Grid나 특정 논문 용어를 필수 UI로 만들지 않는다.
+
+## 6. 재현 비교의 사전 조건과 합격 기준
+
+후속 작업은 별도 isolated prototype에서 수행한다. 제품 의존성을 교체하거나 서버를 변경하지 않는다.
+공개 코드를 사용한다면 라이선스, 고정 commit, 환경, 데이터 이용 조건을 먼저 확인한다.
+실행하지 않은 결과에 성능 점수나 '통과'를 부여하지 않는다.
+
+1. 실제 드라이룸/롤 프레스의 revision 고정 fixture 및 독립 예상 결과 확보.
+2. 인공 사례: 문틀/문/램프, 롤러, 선반, 회전 문, 두 지지체 사이 보.
+3. 각 방식의 **native 표현**과 Figure에 필요한 추가 규칙을 따로 기록.
+4. 고정 간격/두께/반지름 잔차, 실제 부착점·면 차이, 의도하지 않은 변경을 검사.
+5. 불가능한 요구·과잉 제약·복수해·순환·크기 경계·회전·topology 변경을 포함.
+6. 사용자 노출 속성 수뿐 아니라 조작 수, 실패 후 복구, undo 정확성을 비교.
+7. layout/pose 시간, 메모리, 1/100/500 인스턴스 draw call을 실제 renderer에서 측정.
+8. 불변식 위반 0을 목표로 하되 그 검증 범위/오차를 명시한다.
+   생성 성공률과 편집 정확도를 합산한 임의 '완성도 점수'는 만들지 않는다.
+
+현재 완료: 주요 선행 사례의 공식 설명/논문 해당 절 비교, 평가 범위와 반례성 한계 식별.
+미완료: 외부 구현 실행, 동일 자산 재현, 독립 benchmark, 전체 문헌 조사, 최종 형식 채택.
+ShapeMOD PDF의 직접 열기는 크기 제한이 있었고 해당 절은 검색에 제공된 원문 발췌로 확인했다.

package/docs/v3-runtime-extraction.md

@@ -0,0 +1,107 @@
+# V3 런타임 정식 소스 이관 — 그래프·capability·자산
+
+> 현재 구현·검증·제품 연결 상태는 [V3 통합 현황](v3-status.md)을 따른다. 본문의 단계별 연구/검증 기록은 제품 전체 완료 선언이 아니다.
+
+> 최신 작업 기준: [V3 단일 체계 전환](v3-cutover.md). 아래의 V2 유지 및 버전별 제품 연결 방향은 과거 작업 기록이며, 향후 설계 조건에서 제외한다.
+
+## 이번 이관 범위
+
+실험용 JSON 입력 검사와 오류 계약을 `src/v3-json.ts`, `src/v3-contract.ts`의 strict TypeScript 소스로 옮겼다. 기본 빌드에서 JS·타입 선언을 생성하며 기존 package 루트에서 이름이 구분된 API로 내보낸다. package.json·의존성·V2 validate/compile 구현은 변경하지 않았다.
+
+| 공개 API | 책임 |
+|---|---|
+| parseV3Json | JSON 문법, 중복 키, 크기·깊이 제한, 유한 수 검사 |
+| assertV3Json | JS 객체의 순환, getter, 숨은 속성, symbol, 희소 배열 등 손실 직렬화 거부 |
+| v3Utf8ByteLength | 브라우저와 서버의 동일 UTF-8 바이트 계산 |
+| V3ContractError | code/path를 가진 공통 오류 |
+
+**parseV3Json은 모델 의미 검증기가 아니다.** JSON 형식이 올바른 V2 객체도 읽을 수 있다. V3 자산 버전·단위·그래프·appearance 검사는 여전히 자산 컴파일러가 담당한다. 공개된 이름이 전체 V3 지원이나 안정화 완료를 뜻하지 않는다.
+
+## 단일 구현 유지
+
+`docs/prototypes/v3-document.mjs`는 새 모듈을 import/re-export한다. 원래 JSON 검사 구현은 제거했다. `v3-typed-plan.mjs`의 ContractError도 정식 V3ContractError를 다시 내보낸다. 따라서 기존 실험 테스트도 이관된 코드와 같은 오류 타입을 사용한다.
+
+문서·자산의 Buffer.byteLength를 TextEncoder 기반 계산으로 대체했다. 생산 소스에는 docs import, 절대경로, Node 내장 모듈 import가 없다. 실험 도구가 src에 의존하는 방향이며 역방향은 없다.
+
+## 검증 결과
+
+2026-09-21:
+
+- `npm test`: 기존 V2 회귀 및 새 입력 경계 검사 포함 **442개 통과**.
+- `node --test docs/prototypes/v3-*.test.mjs`: **143개 통과**.
+- `npm run build`: 성공, JS와 타입 선언 생성.
+- `node docs/prototypes/v3-runtime-browser.mjs`: 실제 Chrome에서 빌드된 ESM 실행 성공. Buffer/process가 없는 상태에서 한글·이모지 UTF-8 계산과 이스케이프 중복 키 거부 확인.
+
+브라우저 테스트는 생성된 두 모듈을 data URL로 로드하며 의존 URL만 치환한다. Node 폴리필을 주입하지 않는다. 이 테스트는 입력 런타임 검사이며 모델러 캔버스 통합 테스트가 아니다.
+
+## 그래프 평가기 이관
+
+`src/v3-graph.ts`에 기존 평가기 전체를 옮기고 루트 API에 `compileV3Graph`를 추가했다. V2의 `compile`은 변경하지 않았다. `src/v3-graph-types.ts`는 입력/상수/노드, 단위·차원, 좌표계 타입, 형상·배치, 평가 결과와 컴파일된 계획의 공개 타입을 정의한다.
+
+실험 진입점 `docs/prototypes/v3-typed-plan.mjs`는 두 export만 남긴 호환 어댑터다. 단위 계산·위상 정렬·좌표계 검사·형상 생성·반복 배치의 구현을 두 벌 유지하지 않는다. 기존 연산자 버전과 실패 코드를 유지했다.
+
+추가 검증:
+
+- 타입 검사·빌드 성공. 소스 테스트 **445개 통과**, V3 실험 테스트 **143개 통과**.
+- 실제 Chrome에서 빌드된 그래프 평가기를 실행했다. 기본 드라이룸6개, 컨베이어30개, 로봇암10개, 포크리프트20개 형상 및 전체 계산값이 Node 결과와 일치했다.
+- 그래프 원본·반환 타입 정보·평가 결과를 호출자가 수정해도 컴파일된 계획의 이후 계산은 변하지 않는지 소스 테스트로 확인했다.
+- 이 브라우저 검사는 평가 결과 비교다. 실제 제품 모델러 렌더러 연결이나 전체 상태 공간의 브라우저 검증을 뜻하지 않는다. 폭넓은 상태 공간 검사는 기존 Node 실험 테스트가 담당한다.
+
+### 타입 보장의 한계
+
+공개 API와 행렬 계산은 타입을 명시했지만, 서로 다른 값 종류를 전달하는 내부 연산자 dispatch에는 아직 명시적 `Dynamic = any`가 남아 있다. 연산자별 타입·좌표계 계약은 기존 런타임 검사로 검증한다. **strict 빌드 통과가 연산자 전체의 정적 타입 안전성 또는 수학적 완전성을 증명하지 않는다.** 다음 내부 강화 작업은 연산자별 판별 가능한 입력/출력 시그니처로 이 경계를 줄이는 것이다. op/params의 가능한 조합도 현재는 런타임 검사 책임이다.
+
+## Capability·문서·자산 이관
+
+다음 구현을 정식 소스와 패키지 루트 API로 옮겼다. 원래 실험 파일은 호환 re-export만 남긴다.
+
+| 소스 | 공개 API |
+|---|---|
+| v3-capabilities.ts | compileV3Capabilities |
+| v3-document.ts | compileV3Document, parseV3Document, serializeV3Document |
+| v3-asset.ts | compileV3Asset, parseV3Asset, serializeV3Asset, captureV3AuthoredInputs |
+| v3-asset-types.ts | 문서·자산·재질·binding 선언 및 평가 결과 타입 |
+
+버전 식별자는 기존 실험 버전을 유지한다. 정식 소스에 포함되었다고 파일 포맷 안정화나 제품 저장 허용을 선언하지 않는다. package.json과 V2 compile/validate는 변경하지 않았다.
+
+유지한 계약:
+
+- capability 참조의 좌표계·실제 형상 소유권·반복 멤버 출처 확인.
+- 수용 타입/수량 조건이 만족되어도 충돌·안전성은 unverified. 평면 출처 검증도 접촉/적합성 해석 완료를 뜻하지 않는다.
+- 자산에 필요한 appearance·팔레트·분할 preset 및 저장된 기본값의 실행 가능성 검사.
+- 일반 저장은 설계 입력만 캡처하고 동작 미리보기는 명시적 옵션이 있어야 기본값으로 저장.
+- 제품 DB·파일 IO·렌더러는 이 순수 모듈에 포함하지 않음.
+
+자산 계층 이관 당시 검증: 소스 테스트 **448개**, V3 실험 테스트 **143개** 통과. 타입 검사·빌드 성공. 실제 Chrome에서 네 대표 모델의 저장 JSON을 빌드된 모듈로 파싱·컴파일·평가하여 형상, 재질, 팔레트, 입력값, binding이 Node 결과와 일치함을 확인했다. 이것은 계산 결과 일치이며 재질 픽셀 재현이나 제품 화면 연결을 의미하지 않는다.
+
+내부 heterogeneous dispatch에는 앞서 설명한 Dynamic 경계가 capability/asset에도 일부 남아 있다. 공개 타입과 런타임 검사 이관을 완료했지만 모든 내부 접근의 정적 타입 증명까지 완료한 것은 아니다.
+
+## 편집 트랜잭션·workspace 이관
+
+`src/v3-authoring-session.ts`와 `src/v3-editor-workspace.ts`를 추가했다. 패키지 루트에서 `createV3AuthoringSession`, `createV3EditorWorkspace`와 요청·반환 타입을 제공한다. 기존 실험 파일 두 개는 re-export만 남겼다. 이번 두 모듈은 `any` 없이 기존 strict 설정으로 검사한다. 하위 평가기의 내부 Dynamic 경계까지 제거한 것은 아니다.
+
+유지한 편집 계약:
+
+- UI와 AI는 같은 입력 역할·단위·범위 검사, 최종 배치 원자적 평가를 사용한다. origin은 기록용이지 인증 정보가 아니다.
+- preview는 변경하지 않는다. 실제 변경만 undo 기록을 남기고, undo/redo도 revision을 증가시킨다.
+- 다른 모델을 열면 새 context와 빈 편집 이력이 생긴다. 이전 모델의 지연 요청은 거부한다.
+- 설계가 미저장일 때만 이탈을 막는다. 잘못된 새 자산을 열어도 기존 자산은 유지한다.
+- export는 저장 완료가 아니다. 저장 확인은 현재 context/revision 및 내용 일치가 필요하다.
+- 빈 화면은 자산·메시·입력을 비우며 기본 상자를 만들지 않는다.
+
+workspace 이관 당시 검증: 소스 테스트 **451개**, V3 실험 테스트 **143개** 통과, 타입 검사·빌드 성공. Chrome에서 빌드된 workspace를 실행해 preview 비변경성, undo/redo 후 revision4, 오래된 저장 응답 거부, 로봇10개로 전환, 이전 AI context 거부, 저장 snapshot의 포크1500mm 복원, 빈 geometry0개를 확인했다.
+
+별도로 격리 편집 UI에서 포크1275mm 수정 → HTTP 파일 저장 → 로봇 전환 → 저장본 복원 → 빈 화면의 경로를 다시 통과했다. page error0개. 생성된 편집 화면과 빈 캔버스 스크린샷을 직접 확인했다. 이 UI는 제품 서버가 아니며 테스트 후 임시 저장 파일을 정리한다.
+
+### 편집 계층의 남은 제한
+
+- 선언된 입력값 편집과 상자 추가 트랜잭션을 지원한다. 구조 변경과 입력 변경은 workspace의 동일 undo/redo 이력에 포함된다. 다른 primitive 추가·삭제·재질·관계 편집은 남아 있다.
+- context는 한 workspace 안의 열기 세대다. 전역 자산 ID·사용자 권한·영속 대화 세션 ID를 대체하지 않는다.
+- 저장 확인은 외부 저장 계층의 성공 통지를 전제로 한다. DB CAS, 네트워크 재시도, 인증을 제공하지 않는다.
+- read 시 자산을 재컴파일한다. 대형 모델의 증분 평가/렌더링 최적화는 별도 과제다.
+
+## 남은 제품 연결
+
+핵심 입력·그래프·capability·자산·편집 workspace는 src로 이관했다. 제품의 저장·발행·편집·렌더러를 V3 단일 체계로 전환해야 하며, 제품 연결은 아직 미완료다. 파일 저장 실험도 제품 DB 구현으로 간주하지 않는다. 접촉/충돌 연구 모듈과 대표 모델 생성기는 계속 실험 영역에 있다.
+
+다음 단계는 V3 단일 저작·저장·렌더링 경로의 제품 연결이다. 기존 자산은 V3 기준으로 바꾼다. V2 병행 운영을 위한 경로는 추가하지 않는다. 제품 API 배포는 아직 수행하지 않았다.

package/docs/v3-sample-validation-expanded.md

@@ -0,0 +1,106 @@
+# v3 샘플 검증 확대 — 16종
+
+> 현재 구현·검증·제품 연결 상태는 [V3 통합 현황](v3-status.md)을 따른다. 본문의 단계별 연구/검증 기록은 제품 전체 완료 선언이 아니다.
+
+2026-09-20. [1차 검사](v3-sample-validation.md)의 후속이다.
+**현재 v2 함수 검사 / 명시한 v3 의도 후보 계산 / 기구학 수치 실험**을 구별한다.
+테스트가 통과했다는 것은 아래 관찰이 재현됐다는 뜻이며, 결함이 해결됐다는 뜻이 아니다.
+제품 소스, 서버, 원본 샘플을 변경하지 않았다.
+
+## 범위와 재현
+
+제품 시드 14종 전부와 로봇암·갠트리 크레인 fixture 2종, 총 163파트.
+원본 해시는 1차 문서와 같으며 추가 크레인 해시는
+`26b80b129d6a7515828a45acd705fa16146792c53722977a2c6eee3fb363017b`다.
+시험 출력에도 세 파일의 SHA256을 기록한다. DB 최신 모델을 뜻하지 않는다.
+
+```sh
+# figure-model 루트, Node 25.6.0
+node --test docs/prototypes/v3-samples.test.mjs docs/prototypes/v3-more-samples.test.mjs
+```
+
+- 모델 관련 검사 18개 통과(기존 5 + 추가 13).
+- 16종 모두 현행 validate의 errors가 없다. 정책 violations가 없다는 뜻은 아니다.
+- X/Y/Z 배율 각각 0.5, 1, 2의 27조합, 4,401개 파트·배율 조합에서
+  사이징 위치 유한성·양의 유한 외곽 치수 확인. 1배율에서 원본 위치 재현.
+- 이 전수 수치 검사는 접촉·충돌·메시 유효성·미관을 보장하지 않는다.
+- bounds 보조 함수는 현행 sizingPosition/sizingScale/rotatedExtent를 사용한다.
+  polygon 실제 표면이나 둥근 모서리 접촉을 상자 겹침으로 판정하지 않는다.
+
+## 추가 모델별 검사
+
+| 모델 | 검사 종류 | 실행 결과 및 남은 계약 |
+| --- | --- | --- |
+| 믹서 | 명시적 의도 후보 | 원본 body/motor 상자 겹침 5mm. 높이 400/800/1600에 모터 높이를 고정하고 body 상단 참조 시 5mm 유지. 이 의도를 자동 추론한 것은 아님 |
+| AGV | 현행 사이징 | 4개 wheel/hub 중심 일치·원형 단면 유지. 바닥 접촉은 유지되지 않음(아래 수치) |
+| 시그널타워 | 현행 사이징 | 높이 550/1100/2200/3300에서 8쌍의 축방향 연결 간격 유지. 램프 높이 90mm 유지. 짧아지는 전체 범위 검증은 아님 |
+| 작업자 | 현행 사이징 | keepRound=false인 다리·팔·손·헬멧·챙의 2×1×0.5 비균일 치수 변형 유지. 원형만 허용하면 기존 표현력 소실. 이 시드는 관절 없는 정적 모델 |
+| 키오스크 | 원본 치수 + 의도 후보 | screen/bezel 폭·높이 차의 반은 각각 30mm, 앞면 돌출 8mm. 고정 여백 후보는 폭 50에서 불가능. 실제 구멍/접촉 mesh 검사는 아님 |
+| 셀 트레이 | 현행 반복 + 의도 후보 | 0.5/1/2배에서 8셀 유지. 벽 30mm 고정이라는 후보 의도를 적용하면 0.5배에서 옆 여유 -12mm |
+| 화성 트레이 | 현행 반복 + 의도 후보 | cell/contact 모두 8개·pitch 68 유지. 두 반복열의 대응 필요. 고정 벽 후보의 축소 한계는 셀 트레이와 동일 |
+| 롤 크래들 | 실제 상태 채널 수치 | fed 0/25/50/75/100%에서 롤 단면 지름 감소, 길이 1000 유지. 끝 지름 224mm로 core 200mm보다 큼. 강체 운동만으로 지원 불가 |
+| 모듈 파렛트 | 원본 상자 수치 | 발-데크-모듈 높이 연결 일치. terminal 상단은 base 높이보다 45mm 위. base를 강제 containment로 취급하면 기존 자산 거부 |
+| 롤 프레스 | 실제 상태 채널 수치 | nip 0/12/24/120/240mm에서 web 중심은 두 롤 사이 중앙. web 두께 24mm 때문에 nip<24에서 양측 겹침 |
+| 화성 충방전기 | 현행 반복/사이징 | shelf/lamp 개수·pitch·중심 일치. 높이 2799.99→2800mm에서 6→7개, 첫 선반 위치 약 200mm 점프 |
+| 갠트리 크레인 | 독립 계층 이동 실험 | X 3값×Z 3값×하강 3값=27상태. hook-seat에 각 이동 한 번씩 상속, hook과의 Y간격 60mm 유지. 레일 충돌·호이스트 케이블 미검사 |
+
+기존 로봇암·컨베이어·포크리프트·드라이룸의 세부 검사와 한계는 1차 문서를 따른다.
+
+## 실제로 설계를 바꾸는 관찰
+
+### 1. 원형 유지와 바닥 접촉은 별개다
+
+AGV 앞왼쪽 바퀴의 현행 사이징 계산:
+
+| XYZ 배율 | 바퀴 반지름 mm | 바닥면 대비 하단 mm |
+| --- | ---: | ---: |
+| 1,1,1 | 115 | 0 |
+| 1,2,1 | 162.63456 | +67.36544 |
+| 2,1,2 | 162.63456 | -47.63456 |
+
+다른 세 바퀴도 같은 결과다. 원형 복원으로 반지름은 바뀌지만 중심 위치는 다른 규칙을 따른다.
+v3 후보는 바닥 접촉 의도에서 `centerY = floorY + radius`라는 동일 치수 참조를 사용해야 한다.
+원형 유지 옵션이 곧 접촉 보장이라는 전제는 폐기한다. 브라우저 렌더링으로 확인한 결과는 아니다.
+
+### 2. 반복에는 최소 두 가지 의도가 있다
+
+- 컨베이어·충방전기: pitch 유지, 개수 변경.
+- 두 트레이: 개수 유지, 전체 비례 크기 변경.
+
+충방전기 높이 2799.99에서는 6층·첫 선반 하단 379.995mm,
+2800에서는 7층·첫 하단 180mm다. 가운데 정렬된 반복에서 개수가 바뀌기 때문이다.
+오류라고 단정할 수는 없지만, 층 번호·외부 binding·사용자가 보는 이동을 정의해야 한다.
+id 정책 없이 단순 배열 인덱스를 영속 참조로 사용하면 의미가 바뀔 위험이 있다.
+
+트레이의 -12mm는 **벽 두께를 고정한다는 v3 후보**에서 나온 결과다.
+현행 renderer의 벽이 실제로 30mm로 유지된다는 검증은 하지 않았다.
+고정 벽 후보는 `clearance = 36*s − 30 ≥ 0`, 즉 `s ≥ 5/6`이라는 입력 제한을 요구한다.
+원본 크기만 재현하는 변환은 이런 축소 영역의 불가능성을 숨긴다.
+
+### 3. 상태는 위치뿐 아니라 형상을 바꾼다
+
+크래들 `fed`는 rigid transform이 아니라 지름을 700→224로 바꾼다.
+명세가 `W(d,q)`의 J만 지원하고 geometry를 G(d)로 한정하면 이를 표현할 수 없다.
+형상 상태를 G(d,q)로 다룰 범위가 필요하다. 단, 무제한 표현식을 허용하자는 결론은 아니다.
+독립 가변 반지름 r과 소비율 f를 함께 지원하면 `r*(1−0.68*f)`는 전체 입력에 대해
+아핀이 아니다. 고정 상태에서 치수에 대한 아핀성과, 치수·상태 전체에 대한 아핀성을 구별한다.
+현재 r2의 전 범위 증명 주장을 이 경우에 그대로 적용할 수 없다.
+
+### 4. 상자 밖/겹침을 모두 오류로 취급하면 정상 표현도 막는다
+
+파렛트 terminal은 base보다 위에 있고, 롤 프레스는 닫힌 두 롤 사이에 두께 24의 web을 그린다.
+web의 각 측 여유는 `(nip−24)/2`로, nip=0에서 -12mm다.
+압축된 소재의 도식적 표현인지 물리적 간극 오류인지 원본만으로 결정할 수 없다.
+v3는 명시한 접촉·containment·간극 assertion을 검사해야 하며,
+모든 AABB 겹침/이탈을 전역 금지하거나 모두 허용하는 양극단을 피한다.
+
+## 확정 전에 남은 것
+
+1. 반복 의도·생성 단계·안정된 참조의 한 계약으로 두 반복 유형 처리.
+2. geometry feature와 dimension 공유로 바닥·부착·개구부의 실제 일치 보장.
+3. 원형/타원형, 상태 기반 형상 변화의 provider 계약 및 정의역.
+4. 각 샘플 전체를 공통 v3 evaluator로 변환해 크기/상태/반복을 함께 변경하는 시험.
+5. renderer 외형 차분, 충돌/메시 검사, 성능 측정과 사용자 편집 흐름 검증.
+
+이번 확대는 일부 새 모델을 수식에 대입하는 것에 그치지 않고 기존 사이징 함수를 재사용해
+현행 동작을 측정했다. 그러나 완성된 v3 evaluator의 성공으로 포장하지 않는다.

package/docs/v3-sample-validation.md

@@ -0,0 +1,97 @@
+# v3 실제 샘플 대입 검증 — 2026-09-20
+
+> 현재 구현·검증·제품 연결 상태는 [V3 통합 현황](v3-status.md)을 따른다. 본문의 단계별 연구/검증 기록은 제품 전체 완료 선언이 아니다.
+
+후속: [제품 시드 전체 + fixture 2종, 총 16종 확대 검증](v3-sample-validation-expanded.md).
+
+## 판정
+
+**r2를 그대로 확정하면 안 된다.** 실제 샘플은 반복 개수 변화, 복합 운동,
+비대칭 단면의 실제 기준점을 요구한다. 개념을 늘리기 전에 이 요구들을 실행 계약으로 닫아야 한다.
+이 기록은 설계 수치 실험이며 v3 전체 모델 변환·렌더러·제품 테스트 완료가 아니다.
+
+시스템 설계 절차에 따라 요구사항, 실행된 검사, 미검증 범위를 분리했다.
+
+## 원본과 재현
+
+- 제품 시드: `operato-application/packages/operato-figure/server/seed/figure-samples.json`
+  - SHA256: `67af0777503117e17f4c3208fe2d766866dd38f6d92c9bd677e6fc40cf14b053`
+  - 14종을 읽어 부품 이름 중복·부모 참조 검사를 수행. 전체 기능 검증은 아니다.
+- 로봇암: `figure-model/src/fixtures/robot-arm-6dof.json`
+  - SHA256: `46cd08feaf3a7fef9413fd447a1c4dad1e7fb17c2bf3c9d06f212733ae210b5d`
+  - 로봇암은 위 제품 시드 목록에는 없으며 별도 6축 시험 fixture다.
+- 서버 DB의 최신 편집본을 조회하거나 변경하지 않았다. 샘플·package.json·서버 변경 없음.
+
+figure-model 루트, Node 25.6.0:
+
+```sh
+node --test docs/prototypes/v3-samples.test.mjs
+```
+
+5개 검사 통과. 아래의 제한적 수치 불변량에 대한 통과이지 시각 품질 인증이 아니다.
+
+## 모델별 결과
+
+| 실제 모델 | 검사와 결과 | 설계에 미치는 영향 |
+| --- | --- | --- |
+| 로봇암 10파트·6관절 | 정지 자세 원본 좌표 재현, 정지 포함 32자세·192개 관절 pivot 일치, 손가락 사이 거리 70mm 유지 | 단일 강체 부모와 상대 frame으로 이 관절 트리는 표현 가능 |
+| 롤러 컨베이어 17파트 | 현재 production `repeatPlanOfPart` 실행: 길이 1200/2399.99/2400/2400.01/4800mm에 8/15/16/16/32개 | 고정 노드 수의 아핀 DAG만으로 기존 샘플 의미를 보존할 수 없음 |
+| 포크리프트 AGV 20파트 | 실제 lift/reach 키프레임을 읽어 공통 아핀 evaluator에 입력. 3×3 상태에서 carriage 승강 0..2000mm, stage는 절반, reach 0..400mm, 포크 상대 간격 유지 | 같은 상태를 공유하는 운동 정의와 계층 변환 시 중복 적용 방지가 필요 |
+| 드라이룸 6파트 | 두 portal의 실제 path 하단 -60mm, 상단 2900mm. 알려진 U 단면의 하단 4점을 바닥까지 줄인 후보에서 하단 0, 상단 2900, 개구부 상단 2200mm·폭 1400mm 유지 | 외곽 상자 스케일과 단면 편집을 구분해야 함 |
+
+### 로봇암: 좌표계는 가능하지만 링크 크기 변경은 별도 문제
+
+v2의 position과 joint.origin은 정지 모델 좌표다. 이를 부모-relative offset과
+자식-local pivot으로 변환한 뒤 `parent · rest · joint`로 계산했다.
+관절 양쪽에서 계산한 동일 pivot의 월드 위치가 일치하는지 검사했다.
+단순히 부품 중심 거리가 일정하다는 검사보다 구체적인 기구학 불변량이다.
+
+그러나 링크를 길게 만들 때 pivot이 어느 실제 면을 따라야 하는지는 이 fixture의 좌표만으로
+일반적으로 결정할 수 없다. feature 관계를 저작하거나 확인해야 한다.
+링크 리사이즈, 그리퍼 구동, 자기 충돌, IK, renderer와의 동등성은 아직 검증하지 않았다.
+
+### 컨베이어: 반복은 후순위로 밀 수 없다
+
+실제 롤러는 X축 pitch=150mm, 반지름=48mm이고 회전된 실린더다.
+기존 함수에서 2400mm 경계를 넘을 때 개수가 15→16으로 불연속적으로 변한다.
+아핀 치수 계산은 길이·반지름을 표현해도 이 topology 변화 자체를 표현하지 못한다.
+
+반복을 치수 계산과 구분되는 제한된 생성 단계로 둘지, 저작 시 고정 개수로 펼칠지
+명시적으로 결정해야 한다. 후자는 현재의 크기 변경 의미를 보존하지 못한다.
+반복 instance id, 개수 감소 시 외부 binding, 끝 여백, 최대 개수 초과 진단을 먼저 정의한다.
+현재 함수의 최소1·최대100 제한을 그대로 v3의 정답으로 채택한 것은 아니다.
+head/tail 롤러와 반복 롤러의 실제 간섭은 이번 검사에 포함되지 않는다.
+
+### 포크리프트: 평면 채널을 계층으로 옮길 때의 위험
+
+시드는 부모 관계 없이 mast/stage/carriage/fork 각각에 reach=400 이동을 기록한다.
+이를 계층화하고 같은 채널도 복사하면 부모의 400과 자식의 400이 중복될 수 있다.
+변환은 `자식 상대 이동 = 기존 자식 이동 − 새 부모의 상속 이동`으로 재구성해야 한다.
+이는 현재 제품에 중복 버그가 있다는 발견이 아니라 **v3 마이그레이션 위험**이다.
+
+9개 조합은 실제 채널의 시작·끝이 선형 translation이라는 조건을 확인한 뒤 평가했다.
+회전이 섞인 일반 채널을 같은 뺄셈으로 변환할 수 있다는 주장은 아니다.
+
+### 드라이룸: 실제 단면 기준점이 필요
+
+`figure-shape.ts`는 path를 extrusion한 뒤 X축 +90도로 돌리고,
+portal은 X축 -90도로 배치한다. 따라서 이 샘플의 path.y가 모델 Y로 돌아온다.
+하단은 `1500 + (-1560) = -60mm`, 상단은 `1500 + 1400 = 2900mm`다.
+transform.size의 대칭 반치수로 계산하면 이 비대칭 단면의 실제 하단과 다른 답을 낸다.
+
+알려진 직교 U 단면에 한해 하단 좌표 -1560을 -1500으로 옮긴 후보를 메모리에서 검사했다.
+전체 높이를 축소하는 것과 달리 상단·문 개구부 상단·폭은 바뀌지 않는다.
+원본은 수정하지 않았다. 이 연산을 임의 polygon clipping으로 일반화하지 않는다.
+서버 편집본의 같은 문제를 확정하거나 자동 수정 완료를 선언하는 근거로도 쓰지 않는다.
+
+## v3 명세 확정 전 필수 보완
+
+1. 반복 topology와 안정된 참조 정책: 컨베이어 및 트레이.
+2. 실제 geometry feature의 좌표·id 계약: 비대칭 polygon, 문틀 안쪽 면.
+3. 복합 상태/운동 합성과 계층 migration: 포크리프트, 로봇 그리퍼.
+4. 링크 치수와 pivot의 연결: 로봇암을 비균일하게 키워도 관절이 유지되는가.
+5. 나머지 샘플의 의미 검사: 시그널타워 부착, 트레이 반복, 롤 프레스 간극,
+   크래들 scale 채널, 작업자 자세 등을 별도 승인 조건으로 추가한다.
+
+동일 evaluator로 전체 변환된 모델을 생성하고 현재 renderer와 비교하는 단계는 남아 있다.
+이번 결과는 r2의 충분성을 입증한 것이 아니라, 실제 샘플로 부족한 계약을 구체화한 것이다.

package/docs/v3-shapeassembly-reproduction.md

@@ -0,0 +1,99 @@
+# ShapeAssembly 공개 구현: 격리 재현 1차
+
+> 현재 구현·검증·제품 연결 상태는 [V3 통합 현황](v3-status.md)을 따른다. 본문의 단계별 연구/검증 기록은 제품 전체 완료 선언이 아니다.
+
+2026-09-20. 문헌을 읽은 결과가 아니라 공개 interpreter를 직접 실행한 기록.
+**학습 모델/논문 benchmark/실제 Figure 자산의 재현은 아니다.**
+연구 전체의 품질 판정이 아니라 Figure 실행 계약에 대한 적합성 조사다.
+
+## 실행 식별
+
+- upstream: https://github.com/rkjones4/ShapeAssembly
+- commit: `cc22bd84afb65e8e37c7d14bebd9a4a629b5d943`
+- upstream checkout: `/private/tmp/figure-v3-research.T0vBJG/ShapeAssembly`
+- Python 3.12.14, torch 2.8.0, numpy 2.2.6, faiss-cpu 1.12.0.
+- upstream 파일 수정 없음. `git status --short` 출력 없음 확인.
+- 작성한 것은 외부 interpreter를 호출하고 좌표 잔차를 계산하는 별도 probe다.
+- 실행은 단일 Program 계층, CPU, 추상 길이 단위. mm로 해석하지 않는다.
+- 현대 의존성 환경의 결과이며 논문 당시 환경과 동일하다는 주장은 하지 않는다.
+- 오류가 난 사례만 제외하지 않았다. 10개 모두 실행 종료, 예외 없음.
+
+```sh
+/private/tmp/figure-v3-research.T0vBJG/venv/bin/python \
+  docs/prototypes/shapeassembly-probe.py \
+  /private/tmp/figure-v3-research.T0vBJG/ShapeAssembly
+```
+
+환경은 임시 폴더에 있으며 이후 정리될 수 있다.
+probe는 revision이 다르면 중단한다. 제품 package.json/lockfile/서버에는 변경이 없다.
+
+## 코드 사용 경계
+
+[고정 revision LICENSE](https://github.com/rkjones4/ShapeAssembly/blob/cc22bd84afb65e8e37c7d14bebd9a4a629b5d943/LICENSE)에
+상용 제품/서비스 편입을 제외하는 조건이 명시돼 있다.
+현재 연구 검증용 임시 checkout만 사용했고 upstream 소스를 제품 저장소에 복사하지 않았다.
+상용 코드 도입은 별도 권한 검토 없이 진행하지 않는다. 이 기록은 법률 자문이 아니다.
+
+## 측정 방법
+
+각 attach에서 지정한 두 local 점의 실행 후 world 위치 차이를 Euclidean norm으로 측정한다.
+이것은 실제 면 전체 접촉/충돌 검사나 논문의 rootedness 지표와 다르다.
+점 일치 오차와 부품의 크기/중심을 함께 기록했다.
+실행 입력과 전체 출력은 [JSON 기록](prototypes/shapeassembly-probe-results.json),
+실험 코드는 [probe](prototypes/shapeassembly-probe.py)에 있다.
+
+## 관찰 결과
+
+| 사례 | 개수 | 결과 |
+| --- | --- | --- |
+| 본체 높이 1/2/4, 램프 크기 0.2, 프로그램 처음부터 실행 | 3 | 부착점 오차 0, 0, 약 1.19e-7. 램프 크기 유지 |
+| 높이 1인 bbox의 위·아래를 squeeze, aligned=True, 초기 높이 0.5/2 | 2 | 초기 높이 그대로. 위 점 오차 0, 아래 점 오차 각각 0.5/1 |
+| 같은 squeeze, aligned=False | 2 | 높이 1로 변경, 양쪽 점 오차 모두 0 |
+| 부착 후 기존 body의 Cuboid 치수만 다시 실행 | 1 | 램프 부착점 오차 0.5. 후속 부착 재평가 없음 |
+| 같은 자기 점을 bbox 위·아래에 붙이는 모순, 순서 반전 | 2 | 예외 없음. 잔차 [0,1]과 [1,0]; 먼저 실행한 부착을 만족 |
+
+10개 모두 성공이라는 표현을 쓰지 않는다.
+5개는 이 실험에서 요구한 접촉 조건을 만족했고, 나머지는 API 의미 차이와 진단 부재를 드러낸다.
+높이 2 > bbox 높이 1 사례는 생성기 필터의 영역을 벗어날 수 있는 스트레스 입력이다.
+생성기가 그 프로그램을 출력한다는 주장이 아니다. 높이 0.5 사례도 같은 aligned 차이를 보였다.
+
+## 왜 이렇게 되는가
+
+고정 revision의 `code/ShapeAssembly.py`를 확인했다.
+
+- 첫 attach는 지정 점까지 translation한다.
+- 이후 aligned 부품은 기존/대상 상자의 겹침·근접을 이용하는 분기로 간다.
+  지정된 두 점을 항상 정확하게 일치시키는 일반 연립 solver가 아니다.
+- non-aligned 부품의 두 번째 attach는 크기/회전 변경을 사용한다.
+- 기존 Cuboid 선언 재실행은 치수만 갱신한다. 후속 명령을 자동 재실행하지 않는다.
+
+이는 곧바로 upstream 버그라는 판정이 아니다.
+그 interpreter는 명령을 순서대로 실행하는 연구용 구조 생성기이며,
+Figure의 지속적 관계 편집기·모순 진단기와 동일한 계약을 약속하지 않는다.
+특히 증분 치수 변경 사례는 원본 프로그램을 수정해 처음부터 실행하는 정상 사용법과 다르다.
+
+## Figure 설계에 반영해야 할 요구
+
+1. **'붙이기'의 의미가 숨은 alignment flag에 따라 달라져서는 안 된다.**
+   점 일치, 면 정렬, 사이 채우기 각각 무엇을 보장하는지 명시한다.
+2. **편집 정본과 runtime 재평가를 분리한다.**
+   기존 mesh의 치수만 바꾸지 말고 정의된 관계 전체를 일관되게 재계산한다.
+   부분 갱신은 전체 재평가와 결과가 같다는 조건 아래의 최적화다.
+3. **모순은 명시 진단한다.**
+   같은 점을 두 곳에 놓으라는 요청은 순서에 따라 조용히 일부를 포기하지 않는다.
+   선언적 후보에서 순서가 달라도 같은 진단이 나와야 한다.
+4. **크기/회전 변화의 허용 여부를 편집 의도로 구분한다.**
+   '부착'했다는 이유로 두께나 원형을 바꿀 권한까지 생기는 것은 아니다.
+5. **작은 기본 명령과 편의 조작 분리는 참고하되 구현을 통째로 채택하지 않는다.**
+   형상 의미·충돌 처리·실패 복구는 별도의 통과 기준이 필요하다.
+
+## 아직 남은 비교
+
+- ShapeMOD의 사용자 조절값 축소는 이번 interpreter 실험으로 검증된 것이 아니다.
+- 선형 제약 방식과 방향성 있는 치수 정의 방식의 동일 사례 비교.
+- 회전한 면/실제 opening/곡면/관절/반복/큰 모델, 실자산 revision.
+- 재실행 비용과 안전한 부분 갱신 비용, 사용자 조작 수 및 undo.
+- 공식 학습 모델과 데이터 benchmark 재현은 수행하지 않았다.
+
+현재 결정: ShapeAssembly의 작은 구조 언어는 참고하되 **원본 interpreter의 Figure 직접 채택은 보류**.
+r2의 아핀 DAG만 허용할지도 아직 확정하지 않는다.