@hatiolab/figure-model 0.1.30 → 0.1.32

package/docs/v3-design.md

@@ -0,0 +1,388 @@
+# Figure v3 — 3차원 레이아웃의 수학적 계약
+
+> 현재 구현·검증·제품 연결 상태는 [V3 통합 현황](v3-status.md)을 따른다. 본문의 단계별 연구/검증 기록은 제품 전체 완료 선언이 아니다.
+
+> 이 문서는 r1의 수학적 논거를 보존한다. [최소 실행 모델 r2](v3-minimal-model.md)가
+> 현재 설계 후보이며, 이 문서의 독립적인 layout/motion parent 및 상위 Flex/Grid 계약은
+> 확정 요구사항이 아니다. 두 안을 혼합해 구현하지 않는다.
+
+상태: 설계 중인 실행 계약. 구현·렌더링·실자산 검증 완료가 아니다.
+2026-09-20. `assembly-constraints-v3.md`의 초기안을 대체한다.
+
+상위 배치 계약: [3차원 컨테이너·Flex·Grid](v3-layout-system.md).
+이 문서는 좌표·부착·운동의 하위 계약이다. Flex/Grid의 크기 배분과 중첩은 상위 계약을 따른다.
+검증 예제: `node --test docs/prototypes/v3-layout.test.mjs`.
+
+## 1. 목적과 범위
+
+Figure는 저폴리 형상을 쉽게 저작하고 많은 인스턴스를 효율적으로 배치하는 제품이다.
+v3의 핵심은 **치수에 따라 달라지는 3차원 배치 함수**다. 문틀·문짝·표시등은 이 함수의
+입력 예이며 별도의 예외 알고리즘이 아니다.
+
+부품 맞춤 UI와 AI는 공통 레이아웃 언어로 편집한다. 모델·검사·2D·3D가 같은 평가 결과를
+쓴다. 임의 CAD, 물리 시뮬레이션, 일반 비선형 제약 해결은 초기 범위 밖이다. 지원하지 않는
+관계를 그럴듯한 결과로 대체하지 않고 지원 범위를 명시한다.
+
+v2의 불합리한 규칙은 고칠 수 있다. 원본 자산과 확인한 의도를 보존하되, 모든 v2 동작을
+보존하는 것은 요구사항이 아니다. 관계 없는 단독 상자도 정상 모델이며, 미완성 초안의
+저장을 금지하지 않는다.
+
+## 2. 현재 문제의 증거와 진단 교정
+
+| 근거 | 확인한 사실 | 한계 |
+| --- | --- | --- |
+| `src/sizing.ts` | anchor는 Figure 기준 상자의 축에 대한 위치·크기 반응 | 부품의 개구부·부착 좌표계를 직접 참조하지 못한다 |
+| `src/types.ts`, `src/grouping.ts`, `jointOriginPosition` | parent/joint와 부모를 따라 변하는 관절 원점은 이미 있다 | 관계가 전혀 없는 것이 아니라 크기 배치 관계가 부족하다 |
+| `src/gate.ts: spansAt/meets/clumpsOf` | AABB의 연결 개수 증가를 검사 | 실제 접촉·개구부 맞춤·어떤 부품에 연결됐는지 보장하지 못한다 |
+| `src/gate.ts: remedyFor` | 다른 덩어리의 느리게 커지는 부품을 골라 조언 | 실제 맞댄 면을 증명하지 않고 수정 방향을 단정할 수 있다 |
+| `src/gate.ts: sizingReport` | 기본적으로 기준 크기와 7종 2배 검사 | 연속 치수 범위·축소·운동 상태의 증명이 아니다 |
+| anchor 후보 탐색 | 제한된 수정 조합을 탐색 | 실패했다고 v2로 해결 불가능한 것은 아니다 |
+| `src/grouping.ts`, things-scene `figure-real-object.ts` | 재질·운동 frame·크기 반응으로 병합/분리 | 관계 추가가 무료 성능을 보장하지 않는다 |
+
+드라이룸에서 복합 수정안이 생성되지 않은 것은 관찰했다. 고정 revision의 원본을 확보해
+원인과 모든 대안을 검증한 상태는 아니다. 앞서 탐색 실패를 곧바로 모델 표현력의 불가능성으로
+설명한 것은 과도했다. v3 설계의 근거는 일반적인 조립 의도와 일관된 배치 계산의 필요성이다.
+
+## 3. 형식적 문제 정의
+
+입력:
+- 자산 정본 S: 부품 geometry, material, 치수/배치 규칙, 운동 규칙.
+- 인스턴스 치수 벡터 d = (width, height, depth), 단위 mm.
+- 런타임 상태 q: 관절 값·표시 상태·시간.
+- 지원 영역 D: d가 만족해야 하는 유한한 크기 범위와 조건.
+
+출력:
+
+```text
+L(S, d) = { (id_i, s_i(d), c_i(d), R_i, features_i(d)) }   정지 레이아웃
+P(L, q) = { (id_i, M_i(d,q), geometrySpec_i(d)) }           최종 자세
+```
+
+s는 부품의 local 크기, c는 Figure 좌표의 중심, R은 회전 행렬이다.
+M은 최종 rigid 배치 행렬이다. material과 geometry spec은 별도 참조다.
+
+초기 kernel은 다음으로 제한한다.
+1. 명시적 크기·offset·feature 식은 아핀식이다. Flex/Grid의 min/max 활성 집합이
+   바뀌면 결과는 구간별 아핀이며, 전체 범위를 단일 아핀식으로 다루지 않는다.
+2. 정지 회전은 d와 무관한 상수이며 R∈SO(3)이다.
+3. 위치·크기 의존 관계는 유향 비순환 그래프다.
+4. 운동은 레이아웃 완료 후의 강체 변환이다.
+5. 반복 개수 변화는 별도의 유한한 topology 구간으로 취급한다.
+
+고정 topology와 고정 배분 활성 집합 안에서는 치수와 정지 위치가 d에 대한 아핀함수다.
+위상 순서는 여러 개일 수 있지만 단일 writer의 결정적 함수로 평가한 결과는 유일하다.
+일반 제약 시스템에 대한 임의 반복·수치 최적화·수렴 추정이 필요하지 않다.
+범위 밖 표현은 확장 kernel의 별도 계약이 필요하다.
+
+## 4. 좌표계와 부품 기하
+
+Figure 좌표는 오른손, Y 상향, mm다. 배치 원점은 reference box의 바닥 중심이다.
+부품 좌표 원점은 중심이다. renderer 고유 축 변환은 입출력 adapter에서 한 번만 한다.
+
+상자형 부품의 정규화 좌표 u∈[-1/2,1/2]³에 대해 정지 위치는 다음과 같다.
+
+```text
+x_i(u,d) = c_i(d) + R_i diag(s_i(d)) u
+```
+
+비정형 primitive는 `geometrySpec(d)`가 local 형상을 생성한다. 위 상자는 local 치수의
+기준이지 polygon 내부가 모두 채워졌다는 뜻이 아니다.
+
+회전은 정규화 quaternion으로 저장하고 RᵀR=I, det(R)=1을 검사한다.
+Euler 값은 UI에서 변환한다. 잘못된 quaternion/NaN/음수 크기는 명시 오류다.
+계산값을 표시용 반올림으로 되먹이지 않는다.
+
+## 5. 치수 언어와 자유도 소유권
+
+부품의 정지 자유도는 크기 3, 위치 3, 회전 3이다. 각 자유도의 writer는 하나다.
+원본 transform과 제약이 같은 값을 서로 덮어쓰지 않는다.
+
+길이는 mm, 비율은 무차원이다. 허용 식은 길이 상수, 참조, 덧셈/뺄셈, 상수배다.
+두 가변 길이의 곱·나눗셈, 임의 함수, eval은 초기 언어에 없다.
+
+```ts
+type LengthExpr =
+  | { op: 'mm'; value: number }
+  | { op: 'ref'; ref: DimensionRef }
+  | { op: 'add' | 'sub'; left: LengthExpr; right: LengthExpr }
+  | { op: 'mul'; value: LengthExpr; factor: number }
+```
+
+DimensionRef는 instance 크기축, 선언한 dimension, 부품 크기축, feature extent축을 가리킨다.
+compile은 명시적 식을 입력 참조의 아핀식으로 정규화한다. 배분 결과 참조는
+Flex/Grid 연산 노드를 유지한다. 상수계수 유한성·단위·참조·식 크기 상한을 검사한다.
+한 값을 둘이 구동하면 우선순위로 해결하지 않고 중복 writer 진단을 반환한다.
+
+사용자에게는 ‘폭을 따라감’, ‘두께 유지’, ‘사이를 채움’으로 보인다.
+공통 template가 이 식을 생성하며 AI도 같은 API를 사용한다.
+
+## 6. 3차원 정렬의 일반식
+
+대상 feature frame의 Figure 원점 o_t, 회전 R_t, extent e_t를 알고 있다고 하자.
+대상 기준점 계수 a, local offset δ, 부품의 자기 기준점 계수 b,
+추가 정지 회전 Q를 명시한다. a,b의 일반적인 값은 -1/2,0,1/2다.
+
+```text
+R_i = R_t Q
+p_target = o_t + R_t (a ⊙ e_t + δ)
+c_i = p_target − R_i (b ⊙ s_i)
+```
+
+그러면 다음 불변식이 성립한다.
+
+```text
+c_i + R_i(b ⊙ s_i) = o_t + R_t(a ⊙ e_t + δ)
+```
+
+즉 선택한 두 기준점은 선언한 offset을 두고 항상 일치한다.
+이 식은 ‘상단에 램프’, ‘문틀 중심에 문’, ‘회전한 패널 전면에 표시기’를 동일하게 처리한다.
+
+단, **기준점 일치와 면 전체 밀착은 다르다.**
+면 밀착 연산은 추가로 면 법선 정렬과 접선 방향 영역 조건을 요구한다.
+외향 법선이 맞대는 경우 `R_i n_self = −R_t n_target`이어야 한다.
+임의 Q 때문에 이 조건이 깨지면 단순 점 부착으로 낮춰 성공 처리하지 않는다.
+
+축 정렬된 두 경계 사이를 채울 때, 같은 frame의 하한 l, 상한 h,
+좌우 여백 m₋,m₊로 다음처럼 크기와 중심을 동시에 정한다.
+
+```text
+s = h − l − m₋ − m₊
+c_local = (h + l + m₋ − m₊)/2
+```
+
+이 연산이 그 축의 위치와 크기를 모두 소유한다. 음수/0 크기는 범위 불성립이다.
+추가 회전된 부품을 그 영역에 넣는 일반 문제는 같은 연산으로 속이지 않는다.
+고정 회전 상자라면 support extent `|Q|s`로 포함 조건을 검사할 수 있으나
+최적 치수를 역으로 찾는 solver는 초기 kernel에 없다.
+
+## 7. feature: 부착 기준과 실제 개구부
+
+feature는 owner 부품 local frame에 있는 이름 있는 좌표계/영역이다.
+origin은 owner local 길이의 아핀식, orientation은 상수, extent는 길이식이다.
+feature는 geometry·material·draw call을 만들지 않는다.
+
+출처를 구분한다.
+- geometry-bound: shape의 안정된 profile/영역 id와 dimension을 공유한다.
+- author-defined: 저작자가 지정한 기준 영역. 실제 구멍이라는 검증은 별도다.
+
+초기 범위는 bounds, mount frame, rectangular opening이다.
+portal의 opening W/H와 실제 polygon을 만드는 W/H는 동일 dimension을 참조한다.
+개구부 선언과 실제 형상이 따로 수정되는 이중 정본을 금지한다.
+
+geometry provider는 shape spec과 함께 해당 feature binding을 반환해야 한다.
+자유 polygon의 구멍을 자동 추론해 확정하지 않는다. 안정적인 영역을 지정하거나 geometry
+검증이 필요하다. 비볼록/곡선 개구부는 bounding box만으로 포함 여부를 판단하지 않는다.
+지원되는 기하 검사 범위 밖이면 `unverified-geometry-relation`으로 표시한다.
+
+## 8. 의존 그래프와 평가 알고리즘
+
+서로 다른 세 구조를 혼동하지 않는다.
+
+| 구조 | 책임 |
+| --- | --- |
+| 값 의존 DAG | 치수·feature·정지 위치 계산 순서 |
+| 운동 tree/forest | joint 변환의 상속과 적용 순서 |
+| assembly 그룹 | 저작 선택·재사용·노출 조작 묶음 |
+
+부품 id에 대한 순환만 보는 대신 실제 값 참조의 cycle을 검사한다.
+같은 부품의 크기→feature→다른 부품 위치는 허용된다. 자기 크기를 그 feature에서 다시
+계산하면 cycle이다. frame의 원점/회전 의존도 DAG에 포함한다.
+
+```text
+compile:
+  schema/units/IDs → single writer check → resolve references
+  → dependency DAG → cycle diagnostic → topological order
+  → affine coefficients → domain obligations → prepared blueprint
+
+resolve(d):
+  check d∈D → evaluate dimensions/features/rest frames
+  → validate finite positive outputs → immutable resolved layout
+
+pose(q):
+  validate state → evaluate joint motion along forest
+  → final rigid frames → draw/inspect/export
+```
+
+규칙 수 V와 참조 E에 대해 DAG 처리 O(V+E). 명시적 아핀식 평가는 식 수에 선형이다.
+Flex/Grid는 별도의 공간 배분 비용을 더한다. 상위 계약의 복잡도 분석을 따른다.
+표시 이름/배열 순서가 결과를 바꾸지 않는다. 동일 입력·semantic version은 동일 결과를 낸다.
+
+## 9. 운동과 shear 방지
+
+정지 frame을 B_i(d)라 한다. child i의 motion parent가 p이면
+`A_i(d) = inverse(B_p(d)) B_i(d)`를 정지 상대 frame으로 만든다.
+joint local 원점/축을 이 frame 약속으로 정의한 강체 변화 J_i(q,d)에 대해:
+
+```text
+W_i(d,q) = W_p(d,q) A_i(d) J_i(q,d)
+```
+
+joint가 없으면 J=I. q=0이면 모든 J=I여서 정지 레이아웃과 정확히 일치한다.
+hinge는 joint 기준점 주위 `T(h) R(axis,q) T(-h)`,
+slider는 `T(axis × displacement)`다. 축은 정규화한다.
+
+W와 B는 scale이 없는 rigid frame이다. geometry local 크기는 별도로 해결한다.
+따라서 부모의 비균등 scale과 자식 rotation을 곱해 shear를 만들지 않는다.
+renderer는 이미 계산된 크기를 다시 인스턴스 배율로 확대해서도 안 된다.
+
+layout target과 motion parent는 명시적으로 구분한다. ‘부착’ template는 보통 둘 다 지정하고,
+‘위치만 참조’는 motion을 상속하지 않는다. 하나의 joint를 여러 clip/parameter가 동시에
+구동하면 명시적 arbitration 없이 실행하지 않는다.
+
+초기판의 runtime q는 rigid motion/표시 상태만 바꾼다. 형상을 변형하는 q, 닫힌 운동 루프,
+움직이는 두 가지 사이의 재구속은 별도 확장이다. resize 중의 q는 현재 값을 보존하되 새 허용
+영역을 벗어나면 진단하고 사용자 정책을 적용한다. 무언의 clamp는 없다.
+
+## 10. 해의 존재·유일성·보장 범위
+
+**존재**: 참조가 유효하고 DAG이며 각 primitive/feature의 정의역과 모든 양의 치수 조건을
+만족하면 위상 순서로 값을 구성할 수 있다.
+
+**유일성**: 각 값이 상수 입력 또는 이미 결정된 값의 결정적 함수이고 writer가 하나이므로
+위상 순서에 대한 귀납으로 결과가 유일하다. 미지수를 동시에 푸는 일반 solver의 유일성
+주장이 아니다.
+
+**부착 보존**: §6 식을 대입하면 선택 기준점의 일치는 대수적으로 성립한다.
+이는 geometry의 정확성, 면 전체 접촉, 미적 품질을 증명하지 않는다.
+
+**범위 검증**: 초기 d가 직육면체 영역 D에 있고 값 f(d)=a·d+b이면
+각 축의 계수 부호에 따라 하한/상한에서 정확한 최솟값/최댓값을 구한다.
+3변수의 8개 꼭짓점 평가와 동치다. 이 조건은 전체 영역에서 식이 아핀일 때만 성립한다.
+Flex/Grid의 활성 집합이 바뀌면 영역 분할 또는 보수적 구간 검증이 필요하다.
+positive length·gap·linear inequality를 범위 전체에서
+검사할 수 있다. 혼합 affine 조건이 추가된 domain은 box에서 보수적으로 증명하며,
+증명이 안 되면 미증명으로 반환한다. 샘플 성공으로 증명 상태를 바꾸지 않는다.
+
+부동소수 계산에서는 epsilon과 단위 scale을 명시한다.
+초기 비교 허용오차 제안은 `ε = 1e-6 mm + 1e-9 × characteristicLength`.
+제품 조립 clearance와 수치 epsilon은 별개다. epsilon은 테스트/수치 안정성 검토로 확정한다.
+
+회전 관절의 swept collision, 비볼록 개구부 포함, 곡선 geometry는 위 선형 증명 범위 밖이다.
+그 항목은 전문 기하 검사 또는 범위/자세를 밝힌 샘플 검증으로 남긴다.
+‘전 크기/전 자세 안전’이라는 단일 boolean 대신 obligation별 proven/tested/unverified를 반환한다.
+
+## 11. repeat는 topology 연산
+
+고정개수와 고정pitch를 구분한다. 고정pitch의 count는 floor를 포함해 전역 affine가 아니다.
+따라서 count가 일정한 크기 구간별 layout으로 분리한다.
+같은 반복 frame의 index/pitch를 선반·램프·slot이 공유한다.
+
+길이 L 안에서 item width w, 고정pitch p, 양끝 margin m을 지킬 때:
+`count = floor((L−2m−w)/p)+1` (L≥2m+w, p>0).
+공간 부족이면 zero item 허용 여부를 template가 선언한다. 무조건 최소1개로 만들지 않는다.
+centred/end anchored 분포도 명시하고 count 전환점의 양쪽을 검사한다.
+
+복제 id는 template id + 안정된 index다. count 축소로 slot이 사라지면 capability 계층에
+변경을 알린다. 이 정책이 구현되기 전에는 점유된 반복 slot의 안전한 이행을 주장하지 않는다.
+최대 count/geometry 예산 초과는 진단하며 조용히 잘라내지 않는다.
+
+## 12. 두짝문은 일반식의 파생 예
+
+인공 fixture이며 실제 드라이룸의 측정값이 아니다.
+opening W=1440, H=2200, 외곽 margin c=10, 중앙 gap g=10, 두께40 mm.
+X 중심0, Y 하단0인 opening frame을 사용한다.
+
+```text
+leafWidth = (W−2c−g)/2 = 705
+leafHeight = H−2c = 2180
+leftCenterX = −g/2−leafWidth/2 = −357.5
+rightCenterX = +357.5
+centerY = H/2 = 1100
+travel = leafWidth+c = (W-g)/2 = 715
+leftX(q) = leftCenterX−q×travel
+rightX(q) = rightCenterX+q×travel
+```
+
+닫힌 상태는 외곽10mm, 중앙10mm를 유지한다. q=1에서 두 문 내측 끝은 각각 −W/2,+W/2다.
+W가 두 배면 leafWidth 1425, 중심 ±717.5, travel 1435. H가 두 배면 높이 4380.
+이전 초안의 travel=W/2는 간격 g/2만큼 더 이동하는 오류였고, 수치 예제로 교정했다.
+두께/clearance는 고정이다. 개구부를 벗어난 문의 주차 공간은 별도 assertion으로 검사한다.
+
+이 예는 split 영역을 두 개 만들어 각각 채우는 것으로도 동일하게 표현된다.
+lamp는 portal feature 기준점에 고정 크기로 정렬하고, readout은 feature 상대 위치와
+고정 두께를 갖는다. portal 폭이 높이를 따라야 하면 W의 식만 H의 상수배로 바꾼다.
+‘portal 예외’나 ‘lamp 예외’가 evaluator에 필요하지 않다.
+
+## 13. 실행 모델과 성능
+
+```ts
+compileV3(source): PreparedFigureV3 | Diagnostics
+resolveLayout(prepared, dimensions): ResolvedLayout | Diagnostics
+evaluatePose(layout, state): ResolvedFigure | Diagnostics
+inspectResolved(prepared, resolved, profile): Inspection
+```
+
+Prepared는 식/순서/컨테이너/feature binding/geometry spec/운동 구조를,
+Resolved는 실제 크기/rigid frame/feature/slot/port를 반환한다.
+source version, blueprint version, evaluator semantic version을 분리한다.
+2D·3D는 같은 Resolved를 소비하고 관계 의미를 재구현하지 않는다.
+
+compile은 자산 변경 시, layout은 치수 변경 시, pose는 상태 변경 시 처리한다.
+정지 frame에서 매번 관계 전체를 해석하지 않는다. feature/assembly는 scene node를 강제하지 않는다.
+
+동일 material·motion frame·변형 함수를 공유하는 부품은 병합 후보가 된다.
+실제 geometry 병합/instancing 경로가 구현된 경우만 비용 이득으로 계산한다.
+크기별 geometry cache는 제한/퇴출/semantic version 포함 키를 가진다.
+
+같은 모양·치수·상태·LOD로 1/100/500 인스턴스의 draw call, triangle, geometry 공유,
+heap, layout p50/p95, frame p95를 측정한다. 관계 메타데이터만 추가했을 때
+geometry/draw call이 늘지 않아야 한다. 동일 기능 p95 시간 10% 초과 악화 시 성능 리뷰를
+한다(잠정 목표, 실측값 아님). 독립 운동/투명 표현 비용이 늘면 그 차이를 명시한다.
+
+## 14. 저장·검사·발행
+
+driver는 실행 의미이므로 advisory로 무시할 수 없다. required/advisory는 별도 assertion의 속성이다.
+자동 수정이 required를 advisory로 낮춰 합격시키는 것을 금지한다.
+
+| 상태 | 처리 |
+| --- | --- |
+| 불명 참조/순환/중복 writer | 실행 불가 진단, 작업 초안 보관 가능, 정상 blueprint로 배포 불가 |
+| domain 밖/음수 치수 | 해당 크기 사용 불가; 마지막 정상 표시라면 현재 결과가 아님을 명시 |
+| required assertion 위반 | 선언한 지원 범위에서 발행 불가 |
+| required assertion 미증명 | 위반 확정과 구분; 보장 정책/범위 조정 또는 추가 검증 필요 |
+| AABB 분리/미적 권고 | advisory; 파손 확정으로 설명하지 않음 |
+| 외부 parameter/slot 삭제 | 소비 계약 변경으로 revision 정책과 함께 처리 |
+
+근접성이 계약을 대신하지 않는다. geometry-bound feature에 대해 독립 검사와 수치 oracle을 쓴다.
+2배 7종은 회귀 샘플일 뿐 보장의 전부가 아니다. 축소, 범위 끝, mixed scale, seed 고정 중간점,
+joint 경계, 개도 0/0.5/1, repeat 전환점을 포함한다.
+
+기준 상자 비율 변경만으로 영구 발행 금지하지 않는다. 모든 사용처를 알 수 있다는 전제도 없다.
+consumer는 asset revision 고정과 최신판 추종을 명시적으로 지원해야 한다.
+
+## 15. 저작·AI·수정 transaction
+
+사용자 조작은 ‘이 면에 붙이기’, ‘이 공간을 나누어 채우기’, ‘두께 유지’다.
+구동되는 속성에는 참조 대상과 이유를 표시한다.
+explicit 부착의 드래그는 offset 변경, flow item의 드래그는 순서/칸 변경을 기본으로 한다.
+flow의 계산 위치를 수동 좌표로 덮어쓰지 않는다.
+관계 해제는 현재 값을 고정값으로 전환하고 명시적 배치로 이동하며 undo 가능하게 한다.
+
+AI와 자동 수정은 typed edit API를 사용한다. 후보에 baseRevision/sourceHash, 대상 id,
+사전 조건, atomic patch, 관계 변경, 크기/자세별 결과 차, 비용 차와 검증 범위를 포함한다.
+원본 경합 시 재계산, requestId 멱등 적용, undo를 지원한다. 적용/저장/발행 결과를 분리한다.
+
+관계 미선언 시 ‘램프를 문틀 상단에 부착’ 후보를 보여주며 이름/근접 추론을 자동 확정하지 않는다.
+전역 차단 항목이 0이어야만 수정을 제공하는 조건은 폐기한다. 국소 해결과 남은 문제를 구분한다.
+의미/외형을 훼손하며 검사만 통과한 후보를 안전하다고 표시하지 않는다.
+
+## 16. 전환과 구현 단계
+
+id는 불변, label은 표시 이름이다. 기존 name 기반 외부 참조는 자산 전환 시 갱신한다. V2 호환 alias 실행 계층을 유지하는 것은 요구사항이 아니다.
+변환은 원본/hash 보존, v3 후보, 기계적 변환, 의도 선택, 미검증 진단을 반환한다.
+v2의 잘못된 동작을 보존할 의무는 없다. 의도적으로 바뀐 외형은 승인된 차분으로 기록한다.
+초안 저장과 발행 조건을 분리한다. 미지원 consumer에 v3를 부분 해석해 보내지 않는다.
+
+세부 구현 순서와 출하 조건은 [상위 레이아웃 계약 §12](v3-layout-system.md#12-출하-전-단계와-완료-기준)를 따른다.
+fixture는 단독 box, 두짝문, 회전 portal, 원형 roller, 선반+lamp repeat, slot/port,
+의도적 분리, 서로 다른 개도의 portal 두 개를 포함한다.
+실제 드라이룸 revision fixture 취득은 남아 있다.
+현재 수치 예제는 설계 규칙의 검증이며 제품 불량 해결의 증거가 아니다.
+
+## 17. 남은 검증
+
+- geometry profile의 안정된 feature id와 전체 직렬화 schema를 kernel/adapter 구현 전에 고정한다.
+- 회전 형상의 local 치수/normal/공유 geometry를 renderer에서 확인한다.
+- 임의 비볼록 geometry 검사, 비선형식, 움직이는 구조의 재구속은 별도 지원 계약이 필요하다.
+- repeat의 slot 점유 이전과 consumer revision 이행은 전환 기능의 출하 조건이다.
+- 미적 품질, 성능, 수치 범위의 안정성은 형식적 논증만으로 완료되지 않으며 실측이 필요하다.

package/docs/v3-document-contract.md

@@ -0,0 +1,55 @@
+# V3 그래프·capability 직렬화 계약 — 실험판
+
+> 현재 구현·검증·제품 연결 상태는 [V3 통합 현황](v3-status.md)을 따른다. 본문의 단계별 연구/검증 기록은 제품 전체 완료 선언이 아니다.
+
+## 범위와 상태
+
+실험 그래프와 capability 선언을 저장하고 재로드해 의미 검증하는 계약을 구현했다. **전체 Figure V3 제품 파일 포맷 확정이 아니다.** 현재 전체 모델 예제의 재질·분할 수·외부 capability 메타데이터 일부는 어댑터가 공급한다. 그 데이터까지 이 포맷이 저장한다고 주장하지 않는다. 제품 DB·서버·UI는 변경하지 않았다.
+
+후속 [자산 저장 envelope](v3-asset-persistence.md)는 이 document를 감싸 설계 입력·동작 기본값·재질·팔레트·분할 품질을 함께 저장한다. document 단독 포맷과 자산 envelope의 지원 범위를 혼동하지 않는다.
+
+- [JSON Schema draft-07](prototypes/v3-document.schema.json)
+- [저장·읽기·의미 검증](prototypes/v3-document.mjs)
+- [표면 출처 및 round-trip 테스트](prototypes/v3-document.test.mjs)
+
+```
+{
+  version: "figure-v3-prototype-1",
+  model: { version: "r3-spatial-1", inputs, constants, nodes },
+  capabilities: { version: "r3-capability-3", assetFrame, bindings }
+}
+```
+
+위 코드는 구조 설명이며 생략된 값을 포함한 유효 JSON 예제는 아니다. 재현 가능한 실제 선언은 `v3-capability-samples.mjs`의 model/declaration을 사용한다.
+
+## 두 단계 검증
+
+JSON Schema는 필드 구조·자료형·기본 enum·버전을 검사한다. operator 입력 포트별 형식, 단위, 그래프 순환, 참조 소유권, 좌표계, 범위 간 관계는 의미 컴파일러가 검사한다. Schema 통과만으로 실행하거나 인증하지 않는다.
+
+런타임 parser는 내장 구조 검사와 의미 컴파일러를 실행한다. 외부 Schema 검증기 자체를 제품 의존성으로 추가하지 않았다. 테스트는 기존 things-factory의 Ajv 6을 사용해 Schema를 컴파일하고 두 예제를 검증한다. 이 테스트 경로는 현재 개발 환경에 종속적이다.
+
+직렬화는 평가 결과가 아니라 선언을 저장한다. 파생 메시, 캐시, 과거 pose, 성공 판정은 저장 대상이 아니다. 새 입력으로 다시 계산한다. 사용자 UI·AI도 최종적으로 동일 선언/입력을 바꿔야 한다.
+
+## 손실·오류 정책
+
+- 알 수 없는 문서/계약 버전과 추가 필드를 거부한다. 현재 capability V3는 transform 또는 표면 참조 pose를 허용한다. V1/V2를 추측 변환하지 않는다.
+- JSON 키 중복은 마지막 값으로 덮지 않고 거부한다. Unicode escape로 같은 키가 표현된 경우도 포함한다.
+- 잘린 JSON, 비유한 수, undefined, 함수, Date, 순환, sparse array, accessor·숨겨진 속성 등 JSON으로 손실되는 입력을 거부한다.
+- 실험 자원 제한: 1MiB UTF-8, 객체 깊이64, 그래프 node512. 제품 용량 정책으로 확정된 값이 아니다.
+- round-trip은 의미·수치·선언 동일성을 대상으로 한다. 원본 JSON의 공백·키 표기·서식은 보존하지 않는다.
+- 함수는 파일/DB에 직접 쓰지 않는다. 저장 API의 원자성, 권한, 버전 충돌, 마이그레이션은 제품 통합 시 별도로 구현해야 한다.
+
+## 실제 표면 참조
+
+capability contacts는 `placement`와 `feature` 출력 ID로 명시한다. 실제 배치와 표면을 동일 shape에 결속시킨다. 임의의 rigid transform을 받침면으로 쓰거나 다른 shape의 feature를 가져오는 경우 실패한다.
+
+출처 검증과 접촉 검증은 별개다. 출력의 표면 법선은 part의 world 회전을 적용한 바깥 방향이다. feature의 local axes가 표면 법선이라고 가정하지 않는다. box 6면·roundedBox 위아래·cylinder 양 끝면만 지원하며 곡면과 아직 명세되지 않은 provider는 거부한다. 실제 접촉·충돌·안전성은 계속 `unverified`다.
+
+## 이번 검증
+
+1. 로봇암·포크리프트의 선언이 JSON Schema를 통과하고, serialize → parse → compile → evaluate 후 변경된 동작 상태 결과가 동일하다.
+2. 임의 프레임, 다른 shape, 사라진 placement, 중복 contact, cylinder 곡면을 거부한다.
+3. 로봇 상완을 -90/0/90°로 회전하면 실제 surface normal도 같은 회전을 따른다.
+4. 잘린 문서, 중복 키, 구버전, 크기 제한과 손실되는 JavaScript 값을 거부한다.
+
+후속 단계에서 반복 표면 참조, 제한된 payload 접촉/충돌 검사, 전체 asset 직렬화와 공통 편집 workspace를 구현했다. 현황은 [통합 현황](v3-status.md)을 따른다. 제품 편집기·DB 통합과 일반적인 공간·안전성 보장은 아직 미완료다.

package/docs/v3-dryroom-profile-validation.md

@@ -0,0 +1,87 @@
+# 드라이룸: 비대칭 단면 → typed feature → 실제 메시 검증
+
+> 현재 구현·검증·제품 연결 상태는 [V3 통합 현황](v3-status.md)을 따른다. 본문의 단계별 연구/검증 기록은 제품 전체 완료 선언이 아니다.
+
+상태: 독립 V3 실험. 제품/DB/원본 시드 수정 없음.
+`operato-application/packages/operato-figure/server/seed/figure-samples.json`의
+DRY_ROOM portal-in/out과 lamp-in/out을 읽었다. 서버에서 편집된 revision은 검사하지 않았다.
+shell/readout을 포함한 드라이룸 전체 변환도 아니다.
+
+## 1. 구현 범위
+
+동일 typed compiler에 `portal-profile@1`을 추가했다.
+입력은 outer left/right/bottom/top, opening left/right/top, extrusion depth의 8개 길이다.
+입력 경계로부터 실제 XY 단면과 feature를 함께 만든다. 원점은 자동 재중심화하지 않는다.
+조건은 `left < openingLeft < openingRight < right`, `bottom < openingTop < top`, `depth > 0`이다.
+
+이 provider는 **직교 U형 단면**이다. 제품 이름에 대한 엔진 분기는 없지만
+범용 polygon clipping/round/hollow를 해결한 것으로 주장하지 않는다.
+일반 polygon이나 경사진 문틀은 아직 지원하지 않는다.
+
+정점은 각 경계 교점의 이름을 id로 갖는다. feature는 top, bottomLeft, bottomRight,
+openingTop, frontTop이며 모두 같은 경계값을 읽는다.
+opening 아래의 빈 공간 가운데를 '실제 bottom 면'으로 노출하지 않는다.
+feature 축은 provider 축과 같으며 바깥 법선 방향 frame이 아니다.
+
+## 2. 원본 대응
+
+기존 renderer의 polygon extrusion +90° X와 portal의 −90° X를 합치면
+source path는 world XY로 돌아오고 두께는 중심 기준 Z축으로 놓인다.
+독립 어댑터는 이 변환을 적용한다. 원본 path 8점이 그대로 재현됨을 검사했다.
+램프의 원본 상대 위치를 top-front feature 기준 offset으로 표현했다.
+이것은 자동 의도 복원이 아니라 **이 실험에서 명시한 연결**이다.
+
+## 3. 실제 메시 검사
+
+설치된 things-scene의 Three.js를 재사용해 bevel 없는 ExtrudeGeometry를 만들었다.
+램프도 CylinderGeometry로 생성했다. product dependency/package 설정 변경 없음.
+검사기는 float 좌표를 10⁻⁶mm 격자로 묶어 모서리를 비교한다. 원본의 현재 정수 좌표에는
+충분하지만 임의 크기 형상의 보수적 수치 인증 규칙은 아니다.
+
+| 항목 | 전 | 후 |
+| --- | ---: | ---: |
+| 문틀 world 하단 | −60mm | 0mm |
+| world 상단 | 2900mm | 2900mm |
+| 개구부 상단 | 2200mm | 2200mm |
+| 개구부 폭 | 1400mm | 1400mm |
+| 램프 pose | 원본 대응 | 동일 |
+| 문틀 하나의 체적 | 1,359,600,000mm³ | 1,338,000,000mm³ |
+| 삼각형/정점/모서리 | 28/16/42 | 28/16/42 |
+| 방향/짝이 맞지 않는 모서리 | 0 | 0 |
+
+제거 체적은 `2 × 600 × 60 × 300 = 21,600,000mm³`로 두 다리의 아래 돌출과 일치한다.
+모든 삼각형 면적이 양수, signed volume이 양수이며 analytic volume과 일치했다.
+edge incidence 2, 반대 방향 edge pairing, Euler=2를 검사했다.
+이 조건만으로 임의 mesh의 무자기교차를 증명하지 않는다. 여기서는 위 정의역이 보장하는
+단순 U형 extrusion을 대상으로 한다.
+
+ray 검사: 개구부 중앙은 관통, 상부/다리는 충돌, y=−30의 다리는 전에는 존재하고 후에는 없다.
+하단을 2200까지 올려 개구부가 사라지는 입력은 GEOMETRY_DOMAIN으로 거절했다.
+−60/0/100/1000/2199mm의 추가 하단 위치에서도 closed/oriented mesh 검사가 통과했다.
+
+## 4. 시각 확인
+
+같은 삼각형을 소프트웨어 orthographic z-buffer renderer로 그려 직접 확인했다.
+왼쪽은 원본, 오른쪽은 수정 후보, 아래는 하단 확대다. 빨간 선은 앞면 평면의 Y=0 기준선이다.
+후보에서 앞면 하단은 선과 일치하고, 두께 방향 뒷모서리는 투영 때문에 선 위에 보인다.
+상부/개구부/램프가 유지되는 것을 확인했다.
+
+이것은 제품 viewport 스크린샷이 아니다. 원본 재질/PBR/조명/그림자와 app integration은 미검증이다.
+렌더 도중 처음 발견한 바닥선 좌표 혼용과 painter 정렬 문제는 검증 도구에서 수정했다.
+최종 이미지는 world 기준선과 픽셀별 depth 비교를 사용한다.
+
+```sh
+node --test docs/prototypes/v3-dryroom-mesh.test.mjs
+# Pillow + NumPy가 있는 Python 환경 사용. 실제 생성 메시 JSON을 입력한다.
+node docs/prototypes/v3-dryroom-mesh.mjs | python3 docs/prototypes/render-dryroom.py /tmp/figure-v3-dryroom-before-after.png
+```
+
+현재 이미지: `/private/tmp/figure-v3-dryroom-before-after.png` (임시 생성물, 위 명령으로 재생성).
+2개 mesh 검사 통과. 기존 검사와 함께 재실행한다.
+
+## 5. 설계에 대한 결론
+
+외곽 상자의 배율을 바꾸는 것보다, 실제 단면 경계와 feature를 정본으로 다루는 계약이
+이번 사용자 의도를 정확히 표현한다. 전체 도형을 scale하지 않고 하단만 편집할 수 있다.
+하지만 U형 하나의 성공을 모든 단면에 일반화하지 않는다.
+다음은 profile의 방향/곡선/feature 안정성 계약과 typed 반복 통합, 이후 전체 자산 렌더링 검증이다.

package/docs/v3-editor-integration.md

@@ -0,0 +1,59 @@
+# V3 편집 화면 연결 검증 — 실험판
+
+> 현재 구현·검증·제품 연결 상태는 [V3 통합 현황](v3-status.md)을 따른다. 본문의 단계별 연구/검증 기록은 제품 전체 완료 선언이 아니다.
+
+## 완료 범위
+
+저장된 V3 자산을 공통 편집 세션으로 열고, 입력 변경을 평가된 3D 장면으로 전달하는 연결 계층을 구현했다. **제품 모델러·서버·DB에는 아직 연결하지 않았다.**
+
+- 연결 계층: [v3-editor-workspace.ts](../src/v3-editor-workspace.ts) — 실험 mjs는 re-export만 유지
+- 계약 검증: [v3-editor-workspace.test.mjs](prototypes/v3-editor-workspace.test.mjs)
+- 격리 브라우저 검증: [v3-editor-browser.mjs](prototypes/v3-editor-browser.mjs)
+
+원본은 관계 그래프와 저작 입력이다. 메시를 직접 수정한 뒤 그래프로 역추정하지 않는다. 속성창과 AI는 같은 단위·역할·revision 검사 및 편집 트랜잭션을 사용한다.
+
+## 편집 수명 주기
+
+| 동작 | 계약 |
+|---|---|
+| 자산 열기 | 파싱·검증 성공 후 교체. 실패하면 기존 자산 유지 |
+| 속성/AI 수정 | 활성 context와 revision 모두 일치해야 적용 |
+| 다른 자산 열기 | 새 context, revision 0, 빈 undo 기록 |
+| 빈 화면 | 자산·입력·binding·geometry를 모두 비움. 기본 상자를 만들지 않음 |
+| 변경 후 이탈 | 저장하지 않은 설계 변경이 있을 때만 거부. 명시적 폐기 가능 |
+| 동작 미리보기 | 설계 dirty 상태로 간주하지 않음 |
+| export | 저장 문자열 반환만 수행. 저장 완료 표시하지 않음 |
+| 저장 확인 | 동일 context/revision과 현재 내용 일치 확인 후 저장 기준 갱신 |
+
+서로 다른 모델은 둘 다 revision 0일 수 있다. 따라서 revision만 비교하면 늦게 도착한 AI 결과가 다른 모델에 적용될 수 있다. 이번 context는 workspace 안에서만 유일한 열기 세대 식별자다. 제품 저장 자산 ID나 영속적인 대화 ID를 대체하지 않는다.
+
+저장 확인 함수는 호출자가 실제 저장 성공을 확인했다는 전제다. 권한 검증이나 DB 쓰기를 수행하지 않는다. 저장 중 추가 편집이 발생하면 오래된 확인으로 dirty 상태를 지우지 않는다.
+
+## 실제 확인 결과
+
+2026-09-21, 전체 `v3-*.test.mjs` 138개 통과(실패 0). 이번 workspace 테스트 4개 포함. 별도로 실제 Chrome/Three.js 격리 화면에서 다음 경로를 검증했다.
+
+1. 포크리프트 20개 메시 열기.
+2. 포크 길이 850 → 1275mm 변경, 렌더링 입력의 실제 형상 치수 확인.
+3. 임시 메모리에 저장하고 저장 기준 갱신.
+4. 로봇으로 전환해 10개 메시만 남는지 확인.
+5. 이전 포크리프트 context의 AI 요청을 보내 `CONTEXT_CONFLICT` 확인.
+6. 저장본을 다시 열어 1275mm 복원 확인.
+7. 빈 화면으로 전환해 메시 0개·입력 0개 확인.
+
+위 기록은 최초 메모리 저장 검증이다. 이후 저장 버튼을 HTTP 기반 임시 파일 저장으로 연결했고 별도 프로세스 복원·저장 충돌 검증을 추가했다. 최신 범위는 [저장 연결 검증](v3-storage-integration.md)을 따른다. 브라우저 page error는 0개이며 `/private/tmp/figure-v3-editor.png`와 `/private/tmp/figure-v3-editor-empty.png`의 캔버스도 직접 확인했다. 제품 UI 연결을 뜻하지 않는다.
+
+## 제품 연결 시 주의점
+
+현재 figure-ui의 `client/modeller/figure-source.ts`는 장면 파트를 저장용 V2 source로 변환한다. `figure-inspector.ts`와 `figure-modeller-page.ts`의 update-part/update-draft 경로도 V2 draft/parts 중심이다. V3 graph를 이 경로의 `parts`로 가장해 전달하면 원본이 이중화된다.
+
+제품 모델러·저장·AI·렌더러를 V3 단일 경로로 전환한다. 기존 자산은 변환 또는 재작성한다. V2 병행 운영이나 호환 분기는 만들지 않는다. 제품에서는 src에서 빌드한 공용 API를 사용한다.
+
+## 아직 해결하지 않은 범위
+
+- 빈 자산 생성과 상자 부품 추가, 입력 수정, 생성/수정 통합 undo/redo를 지원한다. 격리 UI 버튼까지 검증했지만 제품 버튼 연결, 다른 primitive 추가, 삭제·재질·관계 편집은 남아 있다.
+- 제품 속성창·AI-dock·저장 API·인증·대화 이력 통합은 남아 있다.
+- 실험 렌더러는 색상과 단순 roughness를 사용한다. preset/emissive 등 제품 재질의 완전한 시각적 재현 검증은 아니다.
+- read마다 자산을 재컴파일한다. 증분 평가·렌더링 성능 검증이 필요하다.
+- 이탈 경고 UI, 접근성, 좁은 화면, 네트워크 저장 실패의 제품 UX는 별도 검증해야 한다.
+- 테스트 통과는 모델 안전성이나 제품 배포 완료 판정이 아니다.