@hatiolab/figure-model 0.1.29 → 0.1.31

package/docs/v3-asset-persistence.md

@@ -0,0 +1,66 @@
+# V3 자산 저장·복원 계약 — 실험판
+
+> 현재 구현·검증·제품 연결 상태는 [V3 통합 현황](v3-status.md)을 따른다. 본문의 단계별 연구/검증 기록은 제품 전체 완료 선언이 아니다.
+
+## 구현 범위
+
+그래프/기능 선언에 **설계 입력·동작 기본값·재질·팔레트·형상 품질**을 함께 담는 자산 envelope를 구현했다. 저장된 JSON만으로 이 범위의 평가 결과를 복원한다. 제품 서버·DB·실제 자산을 변경하지 않았다.
+
+- [컴파일·직렬화·읽기 코드](../src/v3-asset.ts) — 파일/DB 쓰기와 구분
+- [JSON Schema](prototypes/v3-asset.schema.json)
+- [네 대표 모델 자산 생성 예제](prototypes/v3-asset-samples.mjs)
+- [검증 테스트](prototypes/v3-asset.test.mjs)
+
+버전은 `figure-v3-asset-experiment-1`이다. **정식 Figure V3 전체 포맷 또는 V2 전체 변환 완료를 뜻하지 않는다.**
+
+## 저장 항목
+
+| 항목 | 의미 |
+|---|---|
+| document | 기존 typed graph + capability V3 선언 |
+| designInputs | 현재 설계 입력값. 선언된 단위 그대로 저장 |
+| stateDefaults | 다시 열 때 사용할 명시적인 동작 기본값 |
+| palette | 사용한 토큰의 색상 snapshot. 미정의 토큰은 거부 |
+| appearance | source placement/member별 재질과 품질 설정 |
+| name | 자산 이름 |
+
+메시·계산된 pose·과거 성공 판정은 저장하지 않는다. 다시 로드하면 선언에서 재계산한다. 이 프로토타입은 팔레트 색상을 고정 snapshot으로 저장한다. 제품 공통 테마를 따라갈지 자산 색상을 유지할지는 별도 정책이 필요하다. 조명·환경맵·카메라는 이 계약에 포함되지 않아 모든 화면의 픽셀 동일성을 보장하지 않는다.
+
+## 설계와 동작의 분리
+
+`captureAuthoredInputs(asset, inputs)`는 공통 편집 세션의 현재 설계 값을 캡처한다. 미리보기 중 움직인 state는 기본적으로 저장하지 않는다.
+
+예: 포크 길이1275mm, lift1000mm로 편집한 후 일반 저장 → 다시 열면 길이1275mm, lift는 이전 기본값0mm다. `{captureStateDefaults:true}`를 명시하면 lift1000mm도 새 기본값이 된다. UI의 '현재 자세를 기본값으로 저장' 같은 별도 동작으로 연결할 수 있다. 현재 UI 버튼을 만든 것은 아니다.
+
+동작 기본값도 선언 범위와 참조를 만족해야 한다. 재로드 직후 실행할 수 없는 기본값은 저장을 거부한다. 런타임 evaluate의 override는 state 입력만 허용한다. 설계 변경은 자산/편집 트랜잭션을 거쳐야 한다.
+
+## 외형과 반복
+
+appearance는 모든 `place@1`/`member@1`에 정확히 하나씩 필요하다. 반복 개수가 늘어나면 새 occurrence는 같은 template member의 appearance를 받는다. occurrence ID마다 재질을 복사해 저장하지 않는다.
+
+원기둥 분할 수는 현재 지원 preset으로 명시 저장한다. 사용자에게 분할 수 직접 입력 UI를 추가하지 않았다. 다른 provider에 임의의 segments를 붙이는 것은 거부한다. 재질은 token/preset/transparent/emissive 범위를 지원하며 미지원 필드를 조용히 버리지 않고 거부한다.
+
+로봇 tool-seat의 기존 capability는 `legacyCapability`라는 비실행 메타데이터로 보존한다. `slot`을 `seat`/`grip`으로 자동 해석하거나 tool-seat solid를 숨기지 않는다. 이 필드는 형식 검사를 거치지만 V3 기능의 검증 완료를 의미하지 않는다.
+
+## 검증 결과
+
+네 모델을 JSON Schema 검증 → 직렬화 → 실제 임시 JSON 파일 쓰기/읽기 → 파싱 → 재컴파일 → 평가했다. geometry·binding·재질·품질·팔레트 결과가 일치했다. 테스트가 만든 임시 파일과 빈 임시 폴더만 종료 시 제거한다.
+
+| 모델 | JSON 크기 | 기본 메시 수 |
+|---|---:|---:|
+| 드라이룸 | 7,558 bytes | 6 |
+| 컨베이어 | 17,089 bytes | 30 |
+| 로봇암 | 15,497 bytes | 10 |
+| 포크리프트 | 26,648 bytes | 20 |
+
+컨베이어 길이를4800mm로 저장한 경우 일반 롤러30개에 segments12와 metal 재질이 모두 복원된다. 누락/중복 appearance, 사라진 토큰, 잘못된 분할 수, design/state 입력 혼합, 잘못된 동작 기본값, 중복 JSON 키, 잘린 JSON 등을 거부한다. 반환 객체나 원래 입력 객체를 변조해도 컴파일된 asset snapshot은 바뀌지 않는다.
+
+## 남은 제품화 범위
+
+- 예제 생성기는 V3로 이미 재저작한 모델을 포장한다. 원본 V2의 animation clip 시간/보간, Holdable 등 자산 수준 capability, placement/base 정책을 전부 변환하는 범용 마이그레이터가 아니다.
+- 원본에 없는 기능을 복원했다고 주장하지 않는다. 기존 자산은 V3 기준으로 변환하거나 재작성하며, 실제 데이터 교체 전에 대상과 복구본을 확인한다. V2 실행 호환성을 보존할 의무는 없다.
+- 네 대표 모델을 넘는 provider/material 확장, 입력 라벨/저작 메타데이터 등은 정식 포맷에서 추가 정의해야 한다.
+- 파일 시스템 원자적 교체·권한·DB revision 충돌·업로드/다운로드 API는 없다. 함수는 문자열을 반환하며 제품 저장소에 직접 쓰지 않는다.
+- 실제 속성창·AI-dock·새 모델/다른 모델 전환·재접속은 통합 테스트가 남아 있다.
+
+저장된 자산을 공통 편집 세션으로 여는 연결과 격리 UI 검증은 [편집 화면 연결 검증](v3-editor-integration.md)에 기록했다. 다음 게이트는 실제 제품의 V3 전용 편집 경로와 저장 API 연결이다. 프로토타입 테스트 수를 제품 배포 완료 여부로 사용하지 않는다.

package/docs/v3-authoring-transactions.md

@@ -0,0 +1,57 @@
+# UI·AI 공통 편집 트랜잭션 — 실행 프로토타입
+
+> 현재 구현·검증·제품 연결 상태는 [V3 통합 현황](v3-status.md)을 따른다. 본문의 단계별 연구/검증 기록은 제품 전체 완료 선언이 아니다.
+
+## 이번 구현 범위
+
+[입력 세션](../src/v3-authoring-session.ts)은 design/state 값 편집을 담당한다. [workspace](../src/v3-editor-workspace.ts)는 상자 추가와 입력 편집을 같은 50단계 undo/redo 이력으로 관리한다. [검증 테스트](prototypes/v3-authoring-session.test.mjs)는 정식 소스 구현을 호출한다. 격리 UI에는 새 Figure·상자 추가·undo/redo 버튼이 연결되어 있다. 제품 AI-dock·일반 그래프 재저작·삭제·재질 편집은 아직 미완료다.
+
+세션은 V3 문서와 초기 입력을 받아 동일 compiler로 검증한다. UI/AI 모두 아래 같은 요청을 사용한다.
+
+```json
+{
+  "origin": "ai",
+  "expectedRevision": 0,
+  "changes": [
+    {"kind": "set-design", "input": "forkLength", "unit": "mm", "value": 1275},
+    {"kind": "set-state", "input": "lift", "unit": "mm", "value": 1000}
+  ]
+}
+```
+
+origin은 출처 메타데이터일 뿐 인증이나 권한을 부여하지 않는다. 사용자 입력의 단위는 선언 단위와 정확히 같아야 한다. AI가 mm 대신 m를 보내도 조용히 추측하거나 변환하지 않는다. 변환이 필요하면 상위 명령 해석 계층에서 명시적으로 처리해야 한다.
+
+## 원자성과 낙관적 동시 편집
+
+- `preview`: 현 상태를 바꾸지 않고 최종 후보 전체를 평가한다. 변경 입력과 추가/삭제/변경 geometry ID, 변경된 binding ID를 반환한다.
+- `apply`: 예상 revision을 검사하고 요청 전체를 다시 평가한 뒤 한 번에 반영한다. preview에서 받은 geometry를 신뢰해 덮어쓰지 않는다.
+- 잘못된 입력·참조·단위·중복 변경 등으로 실패하면 입력·평가 결과·revision·undo/redo 기록 모두 그대로다.
+- 여러 입력을 바꾸는 요청은 중간 상태를 노출하지 않는다. 길이 축소와 사라질 반복 참조의 명시적 변경을 한 배치로 보낼 수 있다.
+- 예상 revision과 현재 revision이 다르면 `REVISION_CONFLICT`다. 자동 merge/재기준화로 사용자 변경을 덮지 않는다.
+- undo/redo도 revision을 증가시킨다. 과거 버전 번호가 다시 유효해지는 ABA 문제를 피한다.
+- no-op은 revision/이력을 늘리지 않는다. 실패한 요청과 no-op은 redo를 지우지 않는다. 새로운 유효 편집은 redo를 지운다.
+
+preview는 승인 토큰이 아니다. 사용자가 본 요청과 apply 요청을 일치시키는 UI와 승인 정책은 아직 연결하지 않았다. 적용 권한 및 AI 자동 실행 정책을 이 모듈이 제공한다고 해석하면 안 된다.
+
+## 결과의 의미
+
+`graph-and-binding-valid`는 선언·입력·그래프·참조가 유효하다는 의미다. 공간/충돌/안전 검사 결과는 여기서 자동 승격하지 않고 미검증으로 둔다. 기존 payload 검사기는 별도 요청이 필요하다. 원본 로봇의 tool-seat 간섭처럼 실제 문제가 있는 모델도 기구학 그래프는 유효할 수 있다.
+
+read/preview/apply 반환값과 초기 선언은 내부 상태와 분리한다. 반환된 메시 배열이나 입력 객체를 바꿔도 세션을 변경하지 못한다. undo는 최근50개 유효 편집까지만 보관하는 실험 제한이며 전체 영속 이력이 아니다.
+
+## 검증
+
+- UI/AI가 같은 편집을 보냈을 때 입력·geometry·binding·차이 결과 일치.
+- preview 불변성, preview 반환값 변조 후 apply 재평가.
+- 반복 참조가 깨지는 축소 거부, 축소+명시적 재지정의 원자적 적용.
+- UI 편집 후 오래된 AI 제안 거부, undo 후에도 오래된 revision 거부.
+- undo/redo의 geometry·binding 복원, 실패/no-op 후 redo 보존, 새 편집 후 redo 삭제.
+- 단위·design/state 역할·중복 입력·잘못된 범위·알 수 없는 입력 거부.
+- 포크 길이/상승/내밈 동시 변경과 binding 추종, 되돌리기.
+- 55회 편집 후 50회 undo 제한, 외부 snapshot 변조 격리.
+
+## 제품 연결 전에 남은 일
+
+세션은 메모리에서 동작한다. 자산 저장 계약과 설계 값/일시적 동작의 분리 정책은 구현했고, 격리 HTTP 파일 저장·복원·충돌 검증도 통과했다. 제품 DB·재접속·다중 사용자 편집, 제품 UI의 preview 승인과 AI 명령 변환·권한 검사는 남아 있다.
+
+다음 제품화 단계는 실제 모델러·AI·저장·렌더러를 이 공통 V3 경로로 전환하는 것이다. 완료된 저장 계약을 다시 설계하는 단계가 아니다.

package/docs/v3-capability-bindings.md

@@ -0,0 +1,109 @@
+# V3 capability binding 설계 기준안
+
+> 현재 구현·검증·제품 연결 상태는 [V3 통합 현황](v3-status.md)을 따른다. 본문의 단계별 연구/검증 기록은 제품 전체 완료 선언이 아니다.
+
+상태: **실행 프로토타입 추가**, 제품 런타임·정식 직렬화 스키마 구현 완료 아님. 로봇암 전체 검증에서 발견한 tool-seat 간섭을 근거로 핵심 feature/frame 계약을 확장하는 부가 계약이다.
+
+## 최소 원칙
+
+적재·파지 기능을 선언하려고 가짜 solid 부품을 만들 필요가 없어야 한다. 반대로 capability가 붙었다는 이유로 실제 부품을 자동으로 숨기거나 충돌 검사에서 제외하지 않는다.
+
+이미 있는 세 가지 역할만 구분한다.
+
+| 역할 | 의미 | 결과에 주는 영향 |
+|---|---|---|
+| geometry | 실제 표시·물리 형상 | 명시한 렌더링/충돌 정책의 대상 |
+| feature/frame | 위치와 방향의 기준 | 동일 typed graph에서 치수·동작을 따라 갱신 |
+| capability binding | 해당 기준에서 허용하는 외부 상호작용 | 의미·자격·점유 검사. geometry나 pose를 암묵적으로 생성하지 않음 |
+
+새 레이아웃/움직임 엔진을 만들지 않는다. binding의 pose는 그래프의 기존 transform 출력을 소비한다. region의 치수도 필요한 경우 동일 그래프의 길이 출력을 소비한다. binding이 그래프 입력을 되먹임해 순환시키는 것은 허용하지 않는다.
+
+## 선언 요소
+
+아래는 의미 계약이며 최종 JSON 필드 이름을 확정한 스키마는 아니다.
+
+- 안정적인 binding ID와 사용자 이름: 예) `fork-load-low` / `하단 포크 적재 위치`.
+- 역할: `seat`(받침/적재) 또는 `grip`(파지). 모호한 `slot`은 이 둘 중 하나로 자동 변환하지 않는다.
+- pose 참조: 로컬 기준 → 자산 기준 변환의 출력 ID. 타입과 좌표계가 일치해야 한다.
+- accepts / capacity: 외부 자산의 허용 유형과 점유 개수. 실제 하중·안전성 보증과는 다르다.
+- 선택적 region: pose 기준의 치수 참조. 영역을 생략했다고 무한 영역으로 취급하지 않는다. 공간 검사를 하지 않았음을 반환한다.
+- 선택적 접촉 참조: 실제 받침면 또는 파지면의 안정적인 feature ID 목록. AABB 근접으로 실제 접촉을 인증하지 않는다.
+
+region은 의미상 허용/검사 영역이다. 표시용 가이드가 될 수 있으나 발행 모델의 메시·draw call에 자동 포함하지 않는다. region과 geometry의 겹침을 곧바로 부품 충돌로 집계하지 않는다. **실제 geometry 간 충돌은 계속 검사한다.**
+
+## 판정 분리
+
+다음 결과를 하나의 boolean 또는 '사용 가능'으로 합치지 않는다.
+
+1. 선언 유효성: ID, 단위, transform 좌표계, 참조, 양의 치수와 capacity.
+2. 자격: accepts와 점유 수 정책.
+3. 공간 적합성: 명시한 검사 방식으로 payload가 영역/면 조건을 만족하는가.
+4. 충돌: 명시한 실제 형상과 접촉 허용 정책으로 검사했는가.
+5. 하중/운영 안전성: 외부 검증이 없으면 `unverified`.
+
+검사를 실행하지 않았으면 성공이 아니라 `unverified`다. 참조가 삭제되었으면 binding을 임의의 다른 부품에 연결하지 않고 `TARGET_ABSENT`로 실패시킨다. 반복 개수 변경으로 대상이 사라지는 경우도 동일하다.
+
+지지/파지의 의도된 접촉은 전역 충돌 제외가 아니다. 허용하는 면 쌍·허용 오차·적용 상태를 명시해야 한다. 오차 및 실제 접촉 solver는 아직 부가 명세가 필요한 영역이며, '완벽한 충돌 판정'을 구현했다고 주장하지 않는다.
+
+## 사례 적용
+
+### 로봇암
+
+기존 tool-seat가 단순한 작업물 위치라면 flange의 feature에 binding을 붙이고 필요시 가이드를 표시한다. 실제 tool-seat cube 제거는 **명시적 재저작/마이그레이션 작업**이다. capability가 있다는 이유만으로 기존 cube를 자동 제거하지 않는다.
+
+실제 기계 부품이라면 cube를 유지하고 치수·손가락 스트로크를 재설계한다. 현재 원본의 gripper 45% 초과 간섭은 어느 의미인지 확정되기 전까지 해결 완료가 아니다.
+
+### 포크리프트
+
+하단/상단 포크에는 각각 독립 binding을 둘 수 있다. 좌우 포크의 실제 상단면으로부터 받침 기준을 정의하고 carriage의 상승·내밈 변환을 공유한다. binding에 lift/reach를 다시 적용하지 않는다.
+
+두 포크 사이의 빈 공간까지 solid로 메우는 '적재 상자'를 만들지 않는다. region 안에 들어간다는 것만으로 포크가 물체를 지지한다고 판정하지 않는다. 실제 받침면과 payload 바닥면의 접촉 검사가 필요하다. 이번 seed에는 이런 binding이 없으며, 전체 포크리프트 실험도 아직 이를 제품 동작으로 추가하지 않았다.
+
+## UI·AI 계약
+
+- 부품 목록과 기능 위치 목록을 구분한다. 이름은 `하단 적재 위치`, `툴 파지 위치`처럼 사용 목적을 나타낸다.
+- 기능 위치 선택 시 기준 프레임·영역·접촉면을 가이드로 보여 준다. 일반 부품 색상이나 shell이라는 대체 이름으로 표현하지 않는다.
+- UI와 AI가 동일 binding ID/그래프 입력을 편집한다. 변경 전후 기준 위치, 영향받는 기능, 실패한 검사를 함께 보여 준다.
+- 실패는 '만들지 못했습니다'가 아니라 대상과 조건을 설명한다. 예: `그리퍼 100%에서 tool-seat와 양쪽 손가락이 겹칩니다. 실제 부품인지 작업물 위치인지 확인이 필요합니다.`
+
+## 구현 게이트
+
+직렬화 schema와 role 정책 확정 → 참조/단위 검사 → 치수·동작 동시 변경 시 binding 추종 테스트 → 삭제·반복 경계·오류 복구 → 실제 접촉 판정 등급 → UI/AI 공동 편집 → 런타임 통합. 현재 문서는 이 구현을 대체하지 않는다.
+
+## 실행 프로토타입 결과 — 2026-09-21
+
+- [컴파일·평가 코드](prototypes/v3-capability-plan.mjs)
+- [로봇암·포크리프트 binding 예제](prototypes/v3-capability-samples.mjs)
+- [회귀 테스트](prototypes/v3-capability-plan.test.mjs)
+
+`compileCapabilities(model, declaration)`은 typed graph를 내부에서 컴파일하고 선언을 snapshot으로 보관한다. 호출자가 제공한 임의의 pose 결과를 받아 검증한 것으로 표시하지 않는다. 현재 실험 계약은 `r3-capability-3`다. V1/V2는 자동 변환하지 않고 거부한다.
+
+`evaluate(input, requests)`는 전체 그래프 평가 후 binding을 평가한다. 필수 참조·좌표계·길이 단위·역할·capacity·중복 ID·알 수 없는 필드를 검사한다. region은 centered-box만 허용하고 길이를 정규화된 mm로 반환한다. 길이가 0 이하이면 전체 호출이 실패한다. 일부 binding 성공 결과나 이전 프레임 결과를 대체 반환하지 않는다.
+
+로봇암 **81개** 치수/6축/그리퍼 조합, 포크리프트 **27개** 길이/상승/내밈 조합에서 추종을 확인했다. geometry는 binding 적용 전과 같으며 robot tool-seat solid도 그대로 남는다. 이 결함을 해결했다고 표시하지 않는다. 포크리프트 기준은 왼쪽 포크의 실제 상단면이며 좌우 상단 frame 두 개를 접촉 후보로 참조한다. 중앙에 가짜 받침 상자를 만들지 않는다.
+
+자격 검사는 요청 종류와 점유 snapshot만 본다. `satisfied`는 **그 두 조건만** 만족한다는 뜻이다. 점유 예약/쓰기·동시성 제어를 하지 않으며 실행 권한이나 실제 적재 승인으로 사용하면 안 된다. 공간 적합성·충돌·안전성은 항상 `unverified`로 반환한다. 통합된 성공 boolean은 제공하지 않는다.
+
+6개 추가 테스트가 정상 추종 외에 누락 참조·좌표계 오류·단위 오류·모호한 slot 역할·잘못된 점유 수·0 크기 region·입력과 반환값 변조 격리·오류 후 복구를 검사한다.
+
+### 아직 구현하지 않은 계약
+
+- `contacts`의 실제 표면 출처와 법선 검사는 아래 단계에서 추가했다. 물체와의 실제 접촉 여부 검사는 여전히 없다.
+- 일반 capability 평가기는 공간·충돌을 미검증으로 둔다. 이후 별도 [상자 적재물·평면 접촉 검사](v3-payload-contact-validation.md)를 추가했으며, 명시적으로 그 검사기를 호출한 경우에만 제한된 포함/접촉 결과를 얻는다. 전역 충돌 solver는 없다.
+- 단일 repeat의 선택 항목은 후속 [반복 참조 검증](v3-repeated-binding-validation.md)에서 연결했다. 개수 축소로 대상이 사라지면 실패하며 중첩 반복/외부 점유 복구는 미지원이다.
+- JSON Schema, 마이그레이션, 제품 런타임, UI/AI 편집과 영속화는 별도 작업이다.
+- 실제 tool-seat의 의미를 결정하거나 해당 solid를 자동 삭제하지 않았다.
+
+## 표면 출처 검증 추가
+
+`contacts` 항목은 문자열 프레임 참조가 아니라 `{placement, feature}`다. 둘 다 typed graph의 출력 ID다.
+
+1. placement는 assetFrame에 놓인 `place@1` 또는 소유권 경로가 검증된 `select-item@1`의 실제 출력이어야 한다.
+2. feature는 `feature@1`에서 나온 출력이어야 한다.
+3. placement와 feature가 **동일한 shape 출력**을 참조해야 한다. 좌표계 이름만 같다고 허용하지 않는다.
+4. 지원하는 평면 feature만 허용한다: box의 6면, roundedBox의 위/아래, cylinder의 start/end.
+5. feature 중심과 바깥쪽 법선을 실제 placement 변환으로 계산한다. 기존 feature frame 축은 provider 축이므로 법선과 혼동하지 않는다.
+
+반환된 `verified-planar-surface`는 **출처가 검증된 평면이라는 뜻**이지 payload와 접촉했다는 뜻이 아니다. 정점/면 영역 전체, 허용 오차, 하중 지지, 충돌 여부는 별도 검사다. curved feature, portal 등의 아직 정의되지 않은 경우를 가짜 평면으로 추정하지 않고 거부한다. 단일 repeat의 선택된 평면은 V3 계약에서 지원한다.
+
+[직렬화 계약 및 테스트 결과](v3-document-contract.md)를 함께 참조한다.

package/docs/v3-common-kernel-experiment.md

@@ -0,0 +1,116 @@
+# 공통 v3 실행 커널 실험
+
+> 현재 구현·검증·제품 연결 상태는 [V3 통합 현황](v3-status.md)을 따른다. 본문의 단계별 연구/검증 기록은 제품 전체 완료 선언이 아니다.
+
+2026-09-20. 제품 구현·출하 명세가 아닌 독립 실험이다.
+원본 seed, package.json, 서버와 제품 코드를 수정하지 않는다.
+
+## 이번에 달라진 검증
+
+이전 샘플 검사는 각 사례의 수치를 별도로 계산하거나 v2 사이징을 호출했다.
+이번에는 **모델 이름을 전혀 모르는 하나의 resolve 함수**에 선언 데이터를 입력한다.
+실제 seed/fixture를 읽는 어댑터는 테스트에만 있고 엔진에는 없다.
+
+- `docs/prototypes/v3-kernel.mjs`: 공통 scalar/frame/geometry/repeat 평가.
+- `docs/prototypes/v3-kernel.test.mjs`: 실제 자료에서 유도한 선언과 독립 기대값 검사.
+
+```sh
+node --test docs/prototypes/v3-kernel.test.mjs
+```
+
+Node 25.6.0에서 6개 검사 통과. 정상 크기·상태 조합 213개와 별도 반례/거절 검사를 실행했다.
+검사 통과에는 잘못된 조합을 재현하는 반례도 포함된다. 모두 제품 동작 성공이라는 뜻이 아니다.
+
+## 최소 실험 계약
+
+실행 순서는 입력 범위 → 값 DAG → 명시 부등식 → 강체 frame → 형상/반복 결과다.
+결과는 새 객체로 반환하고 입력/원본을 변경하지 않는다. 실패 시 부분 결과를 반환하지 않는다.
+
+| 요소 | 지원한 범위 | 의도적으로 아직 없는 것 |
+| --- | --- | --- |
+| 값 | 유한 상수, 참조, 덧셈, 두 값 곱셈, DAG | 단위 타입 검사, interval 증명, 일반 solver |
+| 조건 | left ≥ right, 실패 시 조건 id·부족량 | 최소 충돌 집합, 자동 수정 |
+| frame | 단일 부모, 상대 위치, 축-각 회전 | 일반 affine/shear 변환 |
+| 운동 | slide 또는 hinge, pivot | IK, 폐쇄 기구, 충돌 회피 |
+| 형상 | box, cylinder의 양의 치수 | round/hollow/polygon/material 및 메시 생성 |
+| 반복 | 고정 개수 또는 floor(span/pitch), 최대 개수 초과는 오류 | 0개 허용 정책, 바인딩 복원·삭제 정책, 반복 자식 subtree |
+| 개별 형상 방향 | 반복 배치 후 적용하는 local orientation | 형상별 복합 동작·pivot 일반화 |
+
+실험의 scalar 단위는 fixture에서 약속한다(mm, deg, 무차원 비율). 엔진이 차원 오류를
+잡는다고 주장하지 않는다. 곱셈을 허용했으므로 모든 치수·상태에 대한 전역 아핀성도 없다.
+현재 곱셈 문법을 그대로 최종 명세에 채택하기보다, 상태/치수 분류와 허용 범위를 더 좁혀야 한다.
+
+## 같은 엔진으로 검사한 것
+
+### 로봇암: 96개 크기·자세, 576개 pivot
+
+실제 10파트·6관절 fixture에서 선언을 구성했다. 세로 링크 배율 0.5/1/2와
+32개의 정지/복합 자세를 조합했다. 부모와 자식 양쪽에서 계산한 관절 pivot 위치가 일치한다.
+정지 상태에서는 source의 Y 좌표와 형상 길이에 배율이 적용된 값을 재현한다.
+
+크기 변경 의도는 이번 시험에서 **모든 정지 Y와 Y길이를 같이 변경**하는 것으로 명시했다.
+이는 임의 링크 하나만 변경하는 일반 저작 기능이나 자동 의도 추론을 검증한 것이 아니다.
+관절별 길이 편집, 그리퍼 상태, 자기 충돌, 실제 렌더링은 남아 있다.
+
+### 포크리프트: 27개 크기·승강·내밈
+
+20파트를 구성했다. rest Y의 3배율 × lift 3값 × reach 3값을 조합했다.
+reach frame → stage frame(lift/2) → carriage frame(lift/2)로 상태를 상속한다.
+fork에는 중복 lift를 넣지 않아 carriage의 최종 상승은 lift 한 번이다.
+몸체는 reach를 따르지 않고, 위·아래 fork 간격은 명시된 rest 배율을 따른다.
+
+rect는 box로 축약한 **배치 검증용 proxy**다. 모서리 외형 보존을 검사하지 않는다.
+크기를 바꿔도 lift 범위는 0..2000mm로 유지한 실험이므로 작은 mast에서 물리적
+이동 범위를 만족하는지는 별도의 assertion/충돌 검사로 남는다.
+
+### 롤 크래들: 45개 크기·소비율
+
+20파트 전체가 아니라 roll/core 두 형상에 한정했다.
+반경 배율 3값 × 축길이 배율 3값 × fed 5값을 공통 엔진에서 계산했다.
+`radius = originalRadius × radialScale × (1 − 0.0068 × fed)`를 선언했다.
+회전된 공통 축 유지, 롤 길이와 소비율 독립, roll radius ≥ core radius를 검사했다.
+지지 패드의 접촉과 나머지 18파트의 대응은 검사하지 않았다.
+
+### 컨베이어: 변환 순서 반례와 수정 후보
+
+실제 17파트 중 반복 roller 한 종류만 구성했다. 최초 선언에서 row frame에
+회전을 넣으니 두 번째 롤러 중심이 90도 회전 시 100mm 이상 이동했다.
+이것은 개별 롤러를 회전시키라는 의도가 아니라 줄 전체를 회전시킨 결과다.
+엔진이 의도를 추론해 거절한 것이 아니라 **독립 기대값 검사에서 잘못된 선언을 검출**했다.
+
+수정 후보는 `row placement → repeat offset → shape-local orientation` 순서다.
+폭 5값 × 깊이 3값 × 회전 3값=45조합에서 다음을 검사했다.
+
+- count=floor(width/150), radius=48mm, length=depth−80mm.
+- 회전해도 중심이 `−width/2 + 75 + index*150`에 남는다.
+- 실린더 축 끝점이 회전과 무관하게 의도한 위치에 있다.
+- 롤러의 X 외곽이 허용 길이 안에 있다.
+
+반복은 시작 기준 id `[geometryId,index]`를 사용해 15→16개에서 기존 id가 유지된다.
+이는 기존 중앙 정렬 반복에서의 **의도 변경 후보**다. 모든 기존 모델을 무조건 시작 정렬로
+바꾸겠다는 결정이 아니다. 양끝 롤러와의 간섭, 인스턴스 삭제 후 재등장 참조 정책은 남아 있다.
+
+## 실패 계약 검사
+
+- 입력 범위 초과, NaN.
+- 알 수 없는 값 참조와 값 순환.
+- frame 순환.
+- roll/core의 명시 부등식 위반.
+- 반복 최대100 초과(조용히100으로 잘라내지 않음).
+- 값 정의 순서를 뒤집어도 같은 형상 결과.
+- 실패/성공 실행 전후 원본 선언 불변.
+
+스키마의 모든 잘못된 입력 조합을 검사한 것은 아니다. 선언 데이터는 테스트가 작성한
+신뢰 입력이며, 사용자/AI의 임의 JSON을 받을 제품용 validation 계층은 아직 없다.
+
+## 설계 판단
+
+1. 작은 공통 evaluator로 서로 다른 대표 사례를 처리할 가능성은 확인했다.
+2. 반복 위치와 개별 형상 운동의 순서는 명세에 반드시 들어가야 한다.
+3. geometry도 상태를 입력받아야 한다. 강체 frame에만 상태를 넣는 r2는 부족하다.
+4. 단일 상속으로 포크리프트를 표현할 수 있지만 기존 flat 채널의 자동 변환은 별도 문제다.
+5. **이 실험으로 v3 설계 완성을 선언할 수 없다.** proxy/부분 모델을 전체 fidelity 변환으로
+   확대하고, feature/단위/반복 subtree/참조 정책을 정리한 뒤 렌더러 비교가 필요하다.
+
+다음 검증 우선순위는 geometry feature와 반복 subtree를 공통 계약에 포함하는 것이다.
+그 전에 사례별 옵션을 늘려 미지원 모델을 억지로 통과시키지 않는다.