@hatiolab/figure-model 0.1.30 → 0.1.31

package/docs/v3-minimal-model.md

@@ -0,0 +1,255 @@
+# Figure v3 최소 실행 모델 — r2 설계 후보
+
+> 현재 구현·검증·제품 연결 상태는 [V3 통합 현황](v3-status.md)을 따른다. 본문의 단계별 연구/검증 기록은 제품 전체 완료 선언이 아니다.
+
+> 설계 방향은 [r3 핵심 의미론 기준안](v3-core-semantics.md)으로 대체한다.
+> 이 문서는 과거 가설과 실험 근거로 보존하며 현재 명세와 혼용하지 않는다.
+
+> 채택 보류: [선행 연구 검토](v3-research-review.md)를 먼저 따른다.
+> 아핀 DAG만 허용하거나 배치/운동 부모를 일치시키는 선택도 비교 검증 전의 가설이다.
+> [실제 샘플 대입 검증](v3-sample-validation.md): 컨베이어의 가변 반복을 후속 범위로
+> 미루면 기존 기능을 보존하지 못한다. 실제 단면 feature와 복합 운동 migration도 미완이다.
+> [16종 확대 검증](v3-sample-validation-expanded.md): 상태 기반 형상 변화(G(d,q)),
+> 원형과 바닥 접촉의 분리, 고정 개수/고정 pitch 반복의 구분도 필수 보완사항이다.
+> 현재의 아핀 치수 + 강체 운동만으로 기존 샘플 전부를 표현한다는 주장은 성립하지 않는다.
+> [공통 커널 실험](v3-common-kernel-experiment.md): 213개 크기·상태 조합을 실행했다.
+> 반복 배치와 개별 형상 회전 순서, 상태 기반 geometry가 추가 계약으로 드러났다.
+> 부분 모델/proxy 실험이며 최종 명세가 아니다.
+
+2026-09-20. **검토 중인 후보이며 v3 출하 명세나 제품 구현 완료가 아니다.**
+사용자가 Flex/Grid를 도입 요구가 아닌 사고의 예시로 정정한 내용을 반영한다.
+이 문서는 r1의 컨테이너 중심 접근을 대체하는 방향이다. r1 문서는 비교·반례 기록으로 보존한다.
+어떤 기능도 추가하기 전에 이 최소 모델로 필요한 사례가 실제로 표현되는지 검증한다.
+
+## 1. 출발점: 공간 배정도 유일한 원리는 아니다
+
+“부모가 공간을 배정한다”는 설명은 선반·문짝 배열에는 좋지만 모든 부품에 필요한 것은 아니다.
+롤러에 필요한 것은 길이와 반지름이고, 램프에 필요한 것은 고정 치수와 부착 위치다.
+그것을 위해 보이지 않는 컨테이너·slot·fit 단계를 필수로 만드는 것은 복잡성을 옮기는 일이다.
+
+핵심 질문을 두 가지로 줄인다.
+
+1. **형상을 만드는 치수는 어디서 오는가?**
+2. **그 형상은 무엇을 기준으로 놓이는가?**
+
+형상을 만드는 규칙과 강체 배치는 수학적으로 다른 일이다. 이를 한 속성으로 합치지는 않는다.
+편리한 UI 명칭의 수가 아니라 저장되는 독립 규칙과 규칙 간 우선순위를 줄이는 것이 목적이다.
+
+## 2. 유지/제거/보류 결정
+
+| 항목 | r2 결정 | 이유 |
+| --- | --- | --- |
+| 값당 하나의 정의, 순환 검사 | 유지 | 충돌을 우선순위로 숨기지 않는다 |
+| 이름 있는 형상 기준점/좌표계 | 유지 | 부착 대상이 실제 형상과 같은 치수를 사용해야 한다 |
+| 컨테이너/slot/fit 의무화 | 제거 | 단독 형상·부착에 불필요한 단계다 |
+| Flex/Grid/absolute/fixed 모드 | 핵심 형식에서 제거 | 좌표/배열/분할은 동일한 치수·배치 정의로 표현한다 |
+| intrinsic/basis/preferred/allocated 크기 체계 | 제거 | 서로 다른 크기의 측정·반영 규칙이 불완전했다 |
+| 자동 grow/shrink, auto 다중 span | 보류 | 명시 의도 없이 공간 재배분을 추측하지 않는다 |
+| 형상 치수 유지·원형 유지 | 지원 요구 유지 | geometry 파라미터의 정의로 표현해야 한다 |
+| 운동 | 별도 상태 입력으로 유지 | 크기 변경과 강체 운동을 섞지 않는다 |
+| 런타임 개수 변화 | 후속 범위 | 형상/부착/외부 참조가 사라지는 계약이 먼저 필요하다 |
+| 일반 제약 solver | 도입하지 않음 | 연립 제약 대신 방향이 정해진 계산으로 시작한다 |
+
+이 선택은 지원 범위를 좁힌다. 임의 조건의 최적 배치를 자동으로 찾는 제품이라고 주장하지 않는다.
+대신 자주 쓰는 저작 의도에 대해 안정된 작은 계산을 생성한다.
+자산 사례에서 수식이나 예외가 폭증하면 r2도 기각한다.
+
+## 3. 실행 정본: 치수 값과 배치 frame
+
+### 3.1 치수 값
+
+치수 값은 상수 또는 이미 정의된 치수의 선형 결합이다. 단위는 mm다.
+기본 입력은 width/height/depth. 부품 외곽뿐 아니라 두께·반지름·개구부 폭도 같은 값이다.
+
+```ts
+type LengthDefinition = {
+  constantMm: number
+  terms: { ref: LengthId; coefficient: number }[]
+}
+```
+
+각 LengthId는 하나의 정의만 가진다. 모든 coefficient는 유한한 무차원 상수다.
+참조 없는 값도 같은 형식으로 저장한다. 표시 이름과 id는 분리한다.
+범위 조건은 정의를 덮어쓰는 clamp가 아니라 별도의 검증식이다.
+예: thickness > 0, width - 2*thickness > 0.
+내부 좌표/offset 값은 음수일 수 있다. 모든 LengthId가 양수라는 규칙은 없다.
+
+이 단계에서 min/max 식, 두 변수의 곱/나눗셈, 임의 스크립트는 없다.
+그러므로 정의의 DAG를 펼치면 모든 값은 입력 d에 대한 아핀식 a·d+b다.
+parameter마다 min/max를 자동 적용하지 않는다. 불가능한 치수는 원인과 함께 진단한다.
+
+### 3.2 배치 frame
+
+형상은 하나의 정지 frame을 가진다. frame은 하나의 기준 frame과 상대 변환으로 정의한다.
+기준은 Figure 원점 또는 다른 형상의 이름 있는 feature frame이다.
+컨테이너를 요구하지 않으며, 부품 묶음은 변환 없는 저작 그룹이다.
+
+```text
+B_i(d) = B_parent(d) · T(offset_i(d)) · R_i
+```
+
+offset은 기준 frame 좌표에서의 mm 값 3개다. R은 치수와 무관한 정규화 quaternion이다.
+frame마다 parent와 상대 변환 정의는 하나다. 두 배치 모드를 겹쳐 쓰지 않는다.
+Figure 원점은 바닥 중심, Y 위쪽, 오른손 좌표계다.
+geometry provider의 부품 local 원점은 중심이며 다른 origin이 필요한 provider는 명시 변환한다.
+
+feature도 같은 frame 관계로 나타낸다. 실제 geometry가 쓰는 치수에서 위치를 계산한다.
+예를 들어 문틀 상단 frame의 Y=height/2는 그 문틀 geometry와 같은 height 값이다.
+표시/분석을 위해 만든 별도 AABB를 실제 면이라고 간주하지 않는다.
+
+컴파일러는 치수 참조와 frame/feature 의존을 모두 검사한다.
+feature를 가진 부품을 그 feature 자체에 부착하는 순환은 거절한다.
+다른 부품의 치수를 참조한다고 그 부품의 운동까지 자동 상속하지는 않는다.
+
+### 3.3 형상 provider 계약 — 배치 엔진과의 경계
+
+geometry 입력은 이미 결정된 의미 있는 파라미터다.
+'받은 상자에 어떻게든 맞춘다'는 두 번째 sizing 엔진을 넣지 않는다.
+
+| 대표 형상 | 입력 | 반드시 지킬 관계 |
+| --- | --- | --- |
+| 상자 | width, height, depth | 표면과 ±반치수 feature의 일치 |
+| 원형 롤러 | radius, length | 두 단면 축이 같은 radius 사용 |
+| 사각 중공 프레임 | outerWidth, outerHeight, depth, wall | innerWidth=outerWidth−2wall, innerHeight=outerHeight−2wall |
+| polygon 돌출 | profile 좌표, depth | 안정된 profile id; 유효 단면과 돌출 두께 |
+
+롤러 축은 provider-local Z로 정하고 장면 방향은 배치 frame에서 회전한다.
+프레임의 opening feature는 실제 안쪽 면과 동일 파라미터를 사용한다.
+일반 polygon의 안쪽 offset·rounding 유효성은 아핀식만으로 증명되지 않는다.
+미지원 feature를 bounds로 대체하지 않고 provider 검사 결과를 반환한다.
+
+이 표는 계약의 예시다. 기존 여섯 primitive, hollow, round, material, capability,
+label/port/slot을 모두 포괄하는 provider catalog를 완성하기 전에는 v3 전환을 확정하지 않는다.
+외부 capability slot과 배치 계산을 위한 가상 slot을 혼용하지 않는다.
+
+## 4. 편의 조작은 식을 만드는 방법이지 추가 실행 규칙이 아니다
+
+UI의 조작은 '치수 유지', '두 면 사이 채우기', '균등 나누기', '이 면에 붙이기'다.
+AI도 같은 typed transaction을 생성한다. 일반 사용자에게 수식을 작성하도록 요구하지 않는다.
+
+예를 들어 같은 좌표계의 경계 l,h 사이에서 여백 a,b를 남긴다면:
+
+```text
+size = h-l-a-b
+center = (l+h+a-b)/2
+```
+
+폭 L을 고정 개수 n, 간격 g, 양끝 여백 a,b로 동일 분할하면:
+
+```text
+itemSize = (L-a-b-(n-1)*g)/n
+center(i) = -L/2+a+itemSize/2+i*(itemSize+g)     0≤i<n
+```
+
+n은 저작 시 고정한 양의 정수이므로 1/n은 상수다.
+기본 UI에서는 분할 수를 불필요하게 노출하지 않는다. '두 문짝'과 같은 템플릿이 정한다.
+비균등 분할은 고정 비율 α_i≥0, Σα_i=1로 남은 폭을 나누면 된다.
+최소 크기를 위반하면 자동으로 다른 부품을 줄이지 않고 어떤 조건이 부족한지 알려준다.
+
+이러한 조작이 생성한 식이 유일한 실행 정본이다.
+편의 조작의 label/provenance는 설명용이며 별도로 재계산하지 않는다.
+다시 편집할 때는 식 구조 fingerprint가 생성 당시와 일치하는 경우에만 원래 조작 UI를 복원한다.
+다른 도구가 식을 바꿨다면 이를 감지하고 원본 조작을 무조건 덮어쓰지 않는다.
+이 UX는 구현/사용성 검증이 필요하다. provenance만 붙이면 쉬워진다고 가정하지 않는다.
+
+'이 면에 붙이기'는 전체 rigid placement를 하나의 transaction으로 교체한다.
+자기 면 offset을 빼서 형상의 원점을 구하되 그 보정은 같은 형상 치수를 참조한다.
+정렬식과 position을 두 개의 writer로 저장하지 않는다.
+드래그는 그 정의의 조정 가능한 offset을 편집한다. 의미가 불명확하면 조용히 관계를 해제하지 않는다.
+
+## 5. 운동: 별도 배치 부모를 추가하지 않는다
+
+r1의 독립적인 layout parent와 motion parent를 기본 구조로 두지 않는다.
+배치의 기준 frame이 곧 운동 상속 경로다. 여기에 joint만 상대 강체 변환으로 추가한다.
+
+```text
+W_i(d,q) = W_parent(d,q) · T(offset_i(d)) · R_i · J_i(d,q)
+```
+
+J_i는 i의 정지 local 좌표에서 작용한다.
+slider: T(axis * displacement), hinge: T(pivot) R(axis,angle) T(-pivot).
+q의 정지값은 0이고 J(d,0)=I. geometry에 scale matrix를 중복 적용하지 않는다.
+feature는 소유 형상의 운동을 따른다. feature 아래의 lamp도 따라서 움직인다.
+
+문틀과 함께 움직이는 lamp는 문틀 feature에, 문짝과 함께 움직이는 손잡이는 문짝 feature에 둔다.
+치수는 문짝 폭을 참조하면서 운동은 문틀을 따르는 경우에도 두 규칙은 충돌하지 않는다:
+치수 참조가 운동 부모를 만들지 않기 때문이다.
+
+'움직이는 부품의 정지 위치를 참조하지만 운동은 따르지 않음'을 별도의 inheritance 스위치로
+넣지 않는다. 고정 기준 frame에서 정지 위치 식을 작성한다.
+이 표현이 실제 작업에서 과도하게 복잡한지 검증하고 나서 확장을 결정한다.
+world/viewport 고정은 재사용 Figure 내부 배치와 구별해 scene 계층에 둔다.
+
+## 6. 동일 원리로 다섯 사례를 표현하는가
+
+| 사례 | 치수 정의 | 배치 기준 | 추가 runtime 모드 |
+| --- | --- | --- | --- |
+| 단독 상자 | 상수 또는 입력 치수 참조 | Figure 원점 | 없음 |
+| 문틀+두 문짝 | opening 공유, 문 폭=(openingWidth−2c−g)/2, 두께 상수 | 문틀 opening frame | 두 slider |
+| 램프 | 상수 치수 | 문틀 top feature | 없음 |
+| 롤러 | radius 상수, length=두 지지면 거리−여백 | 지지 frame | 필요 시 hinge |
+| 선반 | 판 두께 상수, 층간 높이는 고정 개수의 분할식 | 동일한 기준 frame | 없음 |
+
+문짝은 q=1에서 내측 끝이 개구부 끝에 놓이도록 travel=(openingWidth−g)/2다.
+판 두께/램프 크기/롤러 반지름은 부모의 배율이 아니라 자신의 치수 정의로 유지된다.
+문틀 폭 변경이 부착 위치에 반영되는 것은 feature가 같은 치수를 사용하기 때문이다.
+
+각 사례를 하나의 공통 evaluator로 실행해야 한다.
+사례별 하드코딩 계산을 따로 실행한 것만으로 최소 모델의 충분성을 주장하지 않는다.
+실제 드라이룸/롤 프레스 revision의 전환 검증은 아직 없다.
+
+## 7. 단순성이 보장하는 것과 보장하지 않는 것
+
+**구성적 존재·유일성:** 유효 참조, DAG, 유효 provider 정의역이면 위상 순서로 값을 계산한다.
+각 값에 정의가 하나이고 각 함수가 결정적이므로 결과도 유일하다.
+일반 제약 문제의 해를 찾았다는 의미가 아니다.
+
+**범위:** 정지 회전이 상수이고 모든 길이 정의가 아핀이므로 정지 frame 위치도 아핀이다.
+직육면체 입력 범위에서 아핀 부등식의 극값은 각 계수 부호로 구할 수 있다.
+부동소수 구현의 보수적 오차 경계가 없으면 인증된 전 범위 증명으로 표시하지 않는다.
+
+**공간 부족:** size<최소 요구라면 형상을 찌그러뜨리거나 관계를 풀지 않는다.
+'문 폭 80이 필요한데 현재 폭은 60'처럼 모자란 치수를 보고한다.
+UI는 원인 입력을 수정하는 후보를 만들 수 있지만 evaluator가 선호도를 추측하지 않는다.
+
+**보장하지 않는 것:** 임의 3D packing, 충돌 없는 운동, 비볼록 면 접촉,
+자동 미적 배치, 임의 연립 제약, 크기에 따른 자동 개수 변경.
+이들을 미지원으로 명시하는 것은 단순성의 대가다. 사용자의 핵심 사례에 필수라면 범위를 재검토한다.
+
+## 8. r1 반례를 어떻게 취급하는가
+
+1. auto Grid 다중 span: 3 tracks, 각 min=10, x₀+x₁≥100, x₁+x₂≥100.
+   r1 결과 [50,70,30]은 150이지만 [10,90,10]이면 110이다.
+   r2는 이 부등식 집합을 자동 배치 입력으로 받지 않는다. 해결했다고 주장하지 않는다.
+   명시적인 칸 치수/분할 의도를 작성하거나 향후 별도 제약 기능의 필요성을 검토한다.
+2. auto 부모의 자식 basis=0/min=100 두 개: 부모는 0, 자식은 합계200.
+   r2는 측정과 배분이라는 두 크기 정본을 두지 않는다. 부모 길이를 child1+child2로
+   정의하거나 자식 치수를 부모에서 정의한다. 양쪽 방향을 동시에 쓰면 cycle 진단이다.
+3. slot size와 geometry fixed/stretch writer 충돌: slot/fit 체계를 제거해 이 충돌은 없다.
+   대신 width와 radius처럼 의미적으로 중복되는 geometry 입력을 provider schema에서 금지해야 한다.
+
+## 9. 자산·UX·성능 출하 조건
+
+- 실행 정본과 파생 geometry, 검사, 2D/3D가 같은 resolved dimensions/frames를 사용한다.
+- 값 DAG/feature frame은 반드시 scene node로 만들지 않는다. compile에서 정리한다.
+- compile은 저작 변경, dimension resolve는 크기 변경, pose는 상태 변경 때 수행한다.
+- 동일 치수/재질/운동의 병합·공유 가능성을 실제 renderer에서 측정한다.
+- v2→v3 변환은 원본 보존, id/외부 binding 대응, 외형 차분, 의도 선택을 포함한다.
+- 새 Figure는 독립 상태에서 시작하고 실패한 후보는 기존 장면에 덧붙이지 않는다.
+- typed edit는 sourceHash 검사, 원자 적용, undo, 재송신 멱등성을 갖춘다.
+- 발행 정책은 invalid / assertion violation / unverified / advisory를 구별한다.
+- 저장 실패와 검증 미완료를 '응답 없음'으로 숨기지 않는다.
+- 고급 식 편집 없이 대표 사례를 만들고 수정하는 작업 수를 실제로 측정한다.
+
+## 10. 다음 판정 기준
+
+이 후보를 확정할 조건은 개념 수가 적다는 사실만이 아니다.
+
+1. 하나의 치수/배치 evaluator로 위 다섯 사례와 회전·중첩·운동을 처리한다.
+2. 기존 primitive/feature catalog에서 수작업 예외가 얼마나 필요한지 확인한다.
+3. '다른 면에 붙이기', '상단 유지하며 아래 돌출 제거', '크기 변경'이 일관된 UI 편집으로 된다.
+4. 기존 자산을 바꾸기 위해 사용자에게 수식을 쓰게 하지 않는다.
+5. 성능·배포 호환성·전체 schema는 검증 전까지 완료로 표시하지 않는다.
+
+현재 상태: 최소 실행 계약 후보를 작성하고 수치 예제를 검증하는 단계.
+컨테이너 방식보다 반드시 우월하다는 결론이나 실제 제품 불량이 해결됐다는 결론은 내리지 않는다.

package/docs/v3-operator-contracts.md

@@ -0,0 +1,148 @@
+# V3 연산·형상 계약 — 첫 실행 가능한 subset
+
+> 현재 구현·검증·제품 연결 상태는 [V3 통합 현황](v3-status.md)을 따른다. 본문의 단계별 연구/검증 기록은 제품 전체 완료 선언이 아니다.
+
+후속: [좌표계 타입과 공간 의존 그래프 통합](v3-spatial-contracts.md).
+아래는 최초 scalar 단계의 기록이며, 현재 확장 범위는 후속 문서를 따른다.
+
+[r3 핵심 의미론](v3-core-semantics.md)을 구현하는 첫 단계다.
+상태: scalar 컴파일러 실험. 정식 V3 전체 schema나 제품 runtime이 아니다.
+시스템 설계 절차에 따라 정적 오류, 입력 의존 오류, 미지원 기능을 구분했다.
+
+## 1. 실행 구조
+
+`docs/prototypes/v3-typed-plan.mjs`는 `compile(source)`와 그 결과의 `evaluate(inputs)`를 제공한다.
+기존 무단위 `v3-kernel.mjs`와 독립이다. 아직 두 엔진을 연결하지 않았다.
+
+```text
+저작 선언 → 구조/단위/출력 소유권/참조/cycle 검사 → 불변 snapshot 실행 계획
+실제 입력 → 단위 정규화 → 정의역 검사 + 연산 → 값과 geometry descriptor
+```
+
+반환 geometry는 실제 mesh가 아니라 provider/version과 해결된 치수다.
+컴파일 후 원본 선언을 변경해도 이전 실행 계획은 영향을 받지 않는다.
+실패한 평가에서 부분 결과를 반환하거나 다음 평가에 값을 남기지 않는다.
+
+## 2. 선언 구조
+
+```json
+{
+  "version": "r3-scalar-1",
+  "inputs": [{"id":"width","unit":"cm","min":1,"max":1000}],
+  "constants": [
+    {"id":"zero","unit":"mm","value":0},
+    {"id":"margin","unit":"mm","value":10}
+  ],
+  "nodes": [{
+    "id":"span",
+    "op":"between@1",
+    "args":["zero","width","margin","margin"],
+    "outputs":{"length":"usableLength","center":"center"}
+  }]
+}
+```
+
+필수 필드 누락과 알 수 없는 필드를 거절한다. node id와 결과 port id는 각각 고유하다.
+출력 포트는 외부 입력/상수/다른 결과 포트와 이름을 공유할 수 없다.
+JSON Schema 파일과 범용 검증 라이브러리를 추가한 것은 아니며, 직접 구조 검사를 구현했다.
+args 순서와 output 이름은 버전별 연산 계약이다. 전체 연산 catalog 완성 전의 제한된 구조다.
+
+## 3. 단위와 차원
+
+| 입력 단위 | 실행 단위/배율 |
+| --- | --- |
+| mm, cm, m | mm: 1, 10, 1000 |
+| rad, deg | rad: 1, π/180 |
+| s | s |
+| ratio, percent | 무차원: 1, 0.01 |
+
+입력 min/max는 선언된 입력 단위다. 평가 시 같은 단위로 범위를 확인한 뒤 정규화한다.
+결과 포트의 타입은 `[길이 지수, 각도 지수, 시간 지수]`로 추론한다.
+각도는 차원 검사에서 무차원 ratio와 구별한다. 면적은 `[2,0,0]`처럼 파생된다.
+
+- add: 같은 차원끼리만.
+- mul/div: 차원 지수 합/차.
+- sin: 각도 입력만, 결과 ratio.
+- bare number를 암묵적으로 mm로 해석하지 않는다. 상수에도 unit이 필수다.
+
+아직 정수 개수·bool·vector·point·frame 타입, d/q 구분은 구현하지 않았다.
+따라서 현재 검증기로 공간 좌표계 혼용이나 topology의 상태 의존까지 잡았다고 주장하지 않는다.
+
+## 4. 연산 catalog
+
+| 연산 | 입력 순서 | 출력 | 값 의존 실패 |
+| --- | --- | --- | --- |
+| add@1 | a,b (동일 차원) | value=a+b | overflow/nonfinite |
+| mul@1 | a,b | value=a*b | overflow/nonfinite |
+| div@1 | a,b | value=a/b | b=0, overflow/nonfinite |
+| sin@1 | angle | value=sin(angle) | nonfinite |
+| between@1 | low,high,marginLow,marginHigh (길이) | length,center | 음수 여백, length≤0 |
+| box@1 | width,height,depth (길이) | xMin,xMax,yMin,yMax,zMin,zMax | 치수≤0 |
+| cylinder@1 | radius,length (길이) | start,end,radialMin,radialMax | 치수≤0 |
+
+`between`은 length와 center를 함께 소유한다. 다른 node가 length만 다시 쓰더라도
+`DUPLICATE_WRITER`다. 순환은 node 경로와 함께 `CYCLE`로 보고한다.
+
+```text
+length = high-low-marginLow-marginHigh
+center = (low+high+marginLow-marginHigh)/2
+```
+
+length=0도 거절한다. 부족량이 0인 경우에도 'positive length required'를 명시한다.
+조용한 clamp, 우선순위 기반 덮어쓰기, 초기값에 의존한 반복 수렴은 없다.
+
+## 5. provider 계약
+
+### box@1
+
+중심 원점의 직육면체다. 치수와 ±반치수 축 좌표를 같은 입력에서 생성한다.
+feature 출력은 local 면의 **스칼라 좌표**이며 완전한 유향 feature frame은 아니다.
+round/hollow는 지원하지 않는다. 기존 rect를 외형 그대로 변환했다고 주장하지 않는다.
+
+### cylinder@1
+
+이 subset은 local Y축 실린더다. start/end는 −length/2,+length/2의 축 좌표,
+radialMin/Max는 −radius,+radius의 방사 extent다.
+끝점 벡터·법선·tangent를 아직 반환하지 않는다. radialMax만으로 임의 표면 부착점이 결정되지 않는다.
+최종 provider의 축 규약은 catalog 통합 시 확정해야 하며 이 실험 편의로 고정하지 않는다.
+
+geometry descriptor와 feature 좌표가 같은 연산의 결과이므로 별도의 bounds로 치수를
+다시 추정하지 않는다. 그렇다고 현재 mesh와 일치함을 검증한 것은 아니다(mesh 미생성).
+
+## 6. 오류의 시점
+
+컴파일: SCHEMA, VERSION, ID, UNIT, TYPE, DUPLICATE_NODE, DUPLICATE_WRITER,
+UNKNOWN_REFERENCE, CYCLE, OPERATOR, RANGE 및 선언 숫자의 NON_FINITE.
+
+평가: INPUT_RANGE, DOMAIN(0 나눗셈/음수 여백), NO_SPACE, GEOMETRY_DOMAIN,
+연산 결과 NON_FINITE, 실제 입력의 누락/추가 필드.
+
+모든 오류는 code/path/detail을 가진다. 이 메시지가 그대로 최종 사용자 문구라는 뜻은 아니다.
+UI에서는 연산 id를 부품/의도 이름으로 연결하고 수정할 입력을 제시해야 한다.
+여러 오류를 한꺼번에 모으는 진단기와 최소 충돌 집합은 미구현이다.
+
+## 7. 실행 증거
+
+```sh
+node --test docs/prototypes/v3-typed-plan.test.mjs
+```
+
+9개 검사 통과:
+
+1. 100가지 폭에서 cm→mm, 양끝 여백, center와 cylinder 끝점 일치.
+2. 각도/길이 혼용은 compile 오류, 공간 부족은 evaluate 오류.
+3. 곱셈/나눗셈의 면적·길이 추론, deg→rad 삼각함수.
+4. 소비율 percent→ratio, 지름 변화, 음수 반지름 거절.
+5. 중복 writer, 순환, 알 수 없는 참조.
+6. 연산 버전과 필드 누락/추가 거절.
+7. 0 나눗셈, 입력 누락·추가·NaN.
+8. 선언 순서 변경과 snapshot 불변성, 실패 후 재평가.
+9. box 치수와 면 좌표 일치.
+
+## 8. 다음 통합 조건
+
+현재는 scalar 타입 검사를 통과해도 frame 계산은 별도 실험기에 있다.
+다음 단계는 **좌표계가 포함된 feature/connection 타입**을 추가하고 하나의 의존 그래프에
+통합하는 것이다. 그 후 profile provider와 반복 cardinality를 확장한다.
+평가점 검사만 있으므로 전 입력 영역의 안전성, floor 경계, 수치 오차 보장은 아직 없다.
+불신 입력에 대한 노드 수·재귀 깊이·자원 예산도 제품 채택 전에 필요하다.

package/docs/v3-payload-collision-validation.md

@@ -0,0 +1,42 @@
+# 적재물 대 모델 전체 부품 충돌 검사 — 실험 v1
+
+> 현재 구현·검증·제품 연결 상태는 [V3 통합 현황](v3-status.md)을 따른다. 본문의 단계별 연구/검증 기록은 제품 전체 완료 선언이 아니다.
+
+## 범위
+
+[실행 코드](prototypes/v3-payload-collision.mjs)는 공간/접촉 검사 결과에 별도 collision 판정을 더한다. **현재 상태의 payload 대 모든 모델 부품**을 검사한다. 모델 부품 상호 간 충돌, 다른 외부 자산, 움직이는 경로 전체의 연속 충돌, 물리 안정성은 범위 밖이다. 따라서 '전역 충돌 완성'이라고 부르지 않는다.
+
+접촉 대상으로 선언된 포크도 충돌 검사에서 제외하지 않는다. 면 접촉과 내부 관통을 구분한다. 기존 geometry·capability 선언·제품 서버는 바꾸지 않는다.
+
+## 수학과 등급
+
+OBB(회전 상자) 간 정적 분리축 검사(SAT)를 사용한다. 양쪽 상자의 축 6개와 축 사이 외적 9개를 검사한다. 근거: David Eberly의 [Dynamic Collision Detection using Oriented Bounding Boxes](https://www.geometrictools.com/Documentation/DynamicCollisionDetection.pdf)의 정적 상자 검사. 이번 구현은 연속 충돌 부분을 구현하지 않는다.
+
+정규화한 후보 축 L에서 투영 반경은 `Σ halfExtent[i] × |axis[i]·L|`이다. 중심 거리의 투영이 두 반경 합보다 크면 분리된다. 분리축이 없을 때 최소 축 겹침이 허용 오차 이내이면 접촉, 그보다 크면 관통으로 분류한다. 단순 world AABB 겹침을 정밀 충돌로 취급하지 않는다.
+
+| 부품 형상 | 경계가 분리됨 | 경계가 겹침 |
+|---|---|---|
+| box | 비관통 | OBB SAT로 면 접촉/관통 구분 |
+| roundedBox, cylinder | 보수적 경계 분리로 비충돌 확인 | 정밀 형상 검사 미구현 → 미검증 |
+| 그 밖의 provider | 미검증 | 미검증 |
+
+전체 상태는 확인된 관통 하나라도 있으면 `failed`, 관통은 없지만 미검증 쌍이 있으면 `unverified`, 모두 분리/허용 오차 내 접촉이면 `satisfied`다. 이 satisfied는 **현재 상태·지정 scope에서 유의미한 관통을 찾지 못했다**는 뜻이며, 하중·안전·받침 적합성 보장이 아니다.
+
+거리 허용 오차는 1e-6mm다. 거의 평행한 축의 외적 길이가 0보다 크고 1e-12 미만이면 수치 불확실성으로 미검증 처리한다. 다른 신뢰할 수 있는 축이 분리를 증명하면 분리 판정은 가능하다. 출력의 minimumAxisOverlap은 검사 축상 최소 겹침이며, 전체 충돌 해결 방향이나 물리 침투 깊이 solver 결과라고 해석하지 않는다.
+
+## 검증
+
+[테스트](prototypes/v3-payload-collision.test.mjs):
+
+- 분리/접촉/관통/완전 포함, 허용 오차 경계, AABB가 겹치지만 OBB는 분리된 경우.
+- 일반적인 3D 회전의 결정적 난수 **1,000쌍**을 기존 Three.js OBB 구현과 대조: 교차174·분리826, 전부 일치. 두 구현은 같은 SAT 원리를 사용하므로 수학적 전 범위 증명이 아니다.
+- 포크 길이3 × 상승5 × 내밈3 × 적재물 yaw5 = **225개 상태**, 부품 쌍 **4,500개** 검사.
+- 높이500mm 적재물은 하단 포크와 접촉하면서 상단 포크를 관통한다. 접촉은 satisfied, 충돌은 failed로 분리 판정.
+- 둥근 본체의 경계 내부에 들어가는 작은 payload는 자동 통과하지 않고 미검증.
+- 잘못된 OBB·정규직교 위반과 거의 평행한 축의 수치 불확실성을 검증.
+
+Chrome에서 `--collision` 실험 화면으로 정상 배치·상단 포크 관통·공중 부유·둥근 본체 내부 배치를 직접 확인했다. 접촉과 충돌 결과를 따로 표시하며 관통한 box 부품을 붉게 표시한다. 작은 적재물이 불투명 본체 안에 가려지는 사례도 있으므로 스크린샷만으로 비충돌을 판정하지 않는다. 임시 이미지: `/private/tmp/figure-v3-full-collision.png`.
+
+## 남은 구현
+
+곡면/일반 메시 narrow phase, 더 넓은 규모의 수치 정책, 파트 간 자기충돌, 움직임 경로 전체 검사, 안정성·접촉 허용 정책, 반복 대상 참조, 실제 제품 UI·AI 통합이 남아 있다. 현재 모듈은 실험 어댑터이며 제품의 발행 차단 조건으로 연결하지 않았다.

package/docs/v3-payload-contact-validation.md

@@ -0,0 +1,56 @@
+# 적재물 공간·평면 접촉 검사 — 실험 v1
+
+> 현재 구현·검증·제품 연결 상태는 [V3 통합 현황](v3-status.md)을 따른다. 본문의 단계별 연구/검증 기록은 제품 전체 완료 선언이 아니다.
+
+## 구현 범위
+
+[검사 코드](prototypes/v3-payload-fit.mjs)는 기존 capability compiler를 내부에서 실행한다. 외부에서 조작한 표면 결과를 받아 인증하지 않는다. 이번 단계에서 지원하는 것은 **상자 적재물 바닥과 box 부품의 top 평면**이다. 전체 물리·충돌·안전성 solver는 아니다.
+
+입력은 binding ID, 물체 종류와 점유 snapshot, 양의 상자 치수(mm), binding 좌표계 기준 중심(mm), Y축 회전각(deg)이다. 기울어진 적재물, 임의 메시, 곡면 받침, 파지 접촉은 이 검사 범위 밖이다. 모든 추가 필드와 잘못된 값은 거부한다.
+
+## 검사 분리
+
+### 1. 공간 포함
+
+binding의 centered-box region이 있을 때만 검사한다. 회전된 payload의 8개 꼭짓점을 region 좌표계에서 검사한다. 볼록한 상자이므로 모든 꼭짓점이 상자 반공간 안에 있으면 전체 상자가 포함된다. region이 없으면 `unverified`이며 무한 공간으로 처리하지 않는다.
+
+### 2. 실제 받침면 접촉
+
+검증된 표면 출처에서 실제 box 폭·깊이를 가져온다. 적재물 바닥의 네 꼭짓점을 각 받침면의 로컬 좌표계로 변환한다.
+
+- 바닥과 받침면의 법선이 평행하고 같은 위쪽 방향인지 확인한다.
+- 바닥 사각형과 받침면 사각형을 2D polygon clipping으로 교차한다. AABB 중첩만으로 접촉 판정하지 않는다.
+- 양의 교차 면적과 바닥 평면의 간격을 함께 검사한다.
+- 명시된 모든 접촉면이 조건을 만족해야 전체 contact 상태가 `satisfied`다. 이것은 이번 '양쪽 포크 접촉' 검사 정책이며 일반 다중 지지 solver를 뜻하지 않는다.
+
+진단은 `ABOVE_SUPPORT`, `PENETRATES_SUPPORT_PLANE`, `NO_POSITIVE_CONTACT_AREA`, `PLANAR_CONTACT`로 나뉜다. 모서리·점 접촉은 양의 면적 조건을 만족하지 않는다. 지원하지 않는 형상/방향은 `unverified`다.
+
+실험 수치 허용오차는 거리 1e-6mm, 면적 1e-6mm², 법선 내적 1e-9이며 결과에 거리·면적 오차를 명시한다. 자산 크기 제한은 payload 치수/중심 절댓값 1e6mm, 회전 ±360°다. 제품의 단위·규모별 수치 정책으로 확정한 값이 아니다.
+
+### 3. 자격·충돌·안전성
+
+물체 종류/점유 조건은 기존 eligibility 결과로 별도 유지한다. 접촉이 성공해도 허용하지 않는 물체일 수 있다.
+
+전역 충돌, 무게중심·힘에 따른 안정성, 하중·운영 안전성은 계속 **미검증**이다. 예를 들어 높이500mm 적재물은 하단 포크에 정확히 닿으면서 상단 포크와 겹칠 수 있다. 바닥 접촉 성공을 전체 배치 성공으로 합치는 boolean을 제공하지 않는다.
+
+`evaluation.bindings[].checks.spatial`은 기존 일반 판정으로 미검증을 유지한다. 새 검사는 반환값 `inspection.containment`와 `inspection.contact`에서 검사 방법과 함께 명시적으로 읽는다. 이 결과 구조는 제품 UI 연결 시 통합할 필요가 있으며 현재 성공 표시용 통합 API가 아니다.
+
+## 검증 결과
+
+[테스트](prototypes/v3-payload-fit.test.mjs):
+
+- 포크 길이3 × 상승3 × 내밈3 × 적재물 yaw3 = **81개 상태**의 양쪽 포크 접촉.
+- 회전0에서는 포크 하나당 교차 면적 `90 × forkLength`mm²와 일치.
+- 공중 부유, 평면 관통, 한쪽 지지 이탈, 정확한 모서리 접촉, 포크 사이에 놓인 좁은 물체를 거부.
+- region 내부에 있지만 뜬 물체, 회전 후 region 밖으로 나간 물체를 구별.
+- 조립 전체를 -65/30/90° 회전해도 상대 접촉 면적이 유지됨을 확인. 중력 안정성은 인증하지 않음.
+- 충돌 가능성이 있는 높은 물체에서도 충돌/안전성은 미검증을 유지.
+- 입력 오류·모델 불변성·오류 후 재평가 검사.
+
+`node docs/prototypes/render-full-dryroom.mjs --payload`로 네 상태(정상 접촉·150mm 부유·20mm 관통·포크 사이)를 Chrome에서 렌더링하고 직접 확인했다. 임시 이미지: `/private/tmp/figure-v3-full-payload.png`. 제품 서버/DB의 실제 자산을 편집하지 않았다.
+
+## 다음 게이트
+
+이 접촉 검사기는 사각 평면과 상자만 대상으로 한다. 반복 요소의 표면 참조는 별도 모듈에서 구현했다. 곡면·rounded profile·임의 메시 및 부분 접촉 정책, 일반적인 전역 충돌·안정성, 제품 UI·AI·저장 통합은 남아 있다. 이 검사 결과만으로 '적재 가능'이나 '안전'으로 표시하면 안 된다.
+
+후속 단계로 [payload 대 모든 부품의 충돌 검사](v3-payload-collision-validation.md)를 별도 추가했다. 상자 쌍은 정밀 OBB 검사, 곡면은 보수적 경계 검사 후 미검증으로 분리한다. 기존 접촉 검사기만 호출하면 충돌은 여전히 미검증이다.

package/docs/v3-repeated-binding-validation.md

@@ -0,0 +1,42 @@
+# 반복 요소의 기능/표면 참조 — 실험 검증
+
+> 현재 구현·검증·제품 연결 상태는 [V3 통합 현황](v3-status.md)을 따른다. 본문의 단계별 연구/검증 기록은 제품 전체 완료 선언이 아니다.
+
+## 이번 구현
+
+전체 컨베이어의 반복 롤러를 선택하고 그 실제 끝면을 binding pose와 contact 후보로 사용할 수 있도록 했다. 반복 template를 별도 메시로 만들거나 선택한 항목을 한 번 더 렌더링하지 않는다.
+
+- [예제](prototypes/v3-repeated-binding.mjs)
+- [테스트](prototypes/v3-repeated-binding.test.mjs)
+- [capability compiler](prototypes/v3-capability-plan.mjs)
+
+현재 선언 버전은 `r3-capability-3`이다. pose는 기존 transform 출력 ID 또는 `{placement, feature}` 중 하나다. 후자는 실제 표면 출처 검사와 같은 경로로 처리한다. V1/V2 입력은 묵시적으로 바꾸지 않고 거부한다. 제품 데이터 마이그레이션을 수행한 것은 아니다.
+
+## 소유권과 좌표
+
+`select-item@1`의 collection → repeat → assembly → template member 경로를 추적한다. 선택 member가 그 assembly에 실제 포함되어 있어야 하며, feature가 해당 member와 동일 shape 출력을 참조해야 한다.
+
+평가 시 선택한 occurrence의 실제 pose와 local feature를 합성한다. 결과의 `targetGeometryId`와 contact의 `geometryId`는 렌더링되는 반복 메시 ID다. template ID나 select 노드 ID로 대체하지 않는다. 예제의 롤러 end는 원기둥의 평면 단면이지 원통 곡면 위 받침점이 아니다. role/accepts는 참조 검증용 예시이며 실제 산업 파지 동작을 인증하지 않는다.
+
+## 개수 변경의 의미
+
+identity는 현재 `[repeat node ID, index, member output ID]`다. 가운데 정렬에서 개수가 바뀌면 항목의 위치는 바뀔 수 있다. 같은 ID는 **같은 선언 순번**이라는 뜻이지, 위치가 고정되거나 실제 물리 부품의 제조번호가 같다는 뜻이 아니다.
+
+- 선택 index는 design 입력 또는 상수로 정한다. state 입력으로 프레임마다 대상이 바뀌는 것을 거부한다.
+- 개수 감소로 해당 index가 없으면 `TARGET_ABSENT`. 가장 가까운 항목·이전 프레임 pose·마지막 항목으로 fallback하지 않는다.
+- 재확장하면 동일 index/member의 ID가 복구된다. 외부 점유나 작업물 할당까지 자동 복구한다는 의미는 아니다.
+- repeat/member 이름 변경은 identity 변경이다. 영속 ID·마이그레이션 정책은 제품 통합 전에 별도 확정해야 한다.
+
+## 검증 결과
+
+전체 컨베이어를 사용해 길이3 × 폭3 × 회전4 = **36개 상태**에서 14번째 롤러 끝면과 법선이 실제 occurrence를 따라가는 것을 확인했다. geometry 개수는 binding 추가 전과 같다.
+
+14번째 항목 존재 경계 `length=2336mm`에서는 성공하고 `2335.999mm`에서는 실패한다. 정상 → 축소 실패 → 정상 복귀 후 결과가 처음과 같다. index를 사용자가 명시적으로 바꾸면 대상 ID가 바뀐다.
+
+다른 shape의 feature, assembly에 없는 member, state 기반 index, 잘못된 binding frame을 거부한다. JSON Schema 검증과 저장/재로드·노드 순서 변경 이후에도 대상 ID와 실패 동작을 유지한다.
+
+이 단계는 수치·참조 검증이다. 새 UI를 구현하거나 브라우저 편집 흐름을 시험한 것으로 계산하지 않는다.
+
+## 남은 범위
+
+중첩 repeat, 임의 collection 연산, occurrence별 persistent UUID, 삭제/재생성 후 외부 점유 처리, UI의 선택 유지/오류 복구 안내는 아직 없다. 지지·파지 기능의 실제 물리 조건은 별도 검사이며 이번 참조 검증만으로 성공 처리하지 않는다.