@operato/scene-storage 10.0.0-beta.44 → 10.0.0-beta.46

package/test/test-crane-rotation-reach.ts

@@ -0,0 +1,218 @@
+/*
+ * Crane.findAdjacentSlots 의 reach 검사 — rotation 적용 검증.
+ *
+ * 핵심 가설 (사용자 보고 narrow 의 source):
+ *   - StorageRack 정상 = rotation 0 모델 → world X 차 검사 와 rail-local X 가 일치.
+ *   - RackGrid narrow = rotation π/2 모델 → rail X axis = world Z. 그러나 기존
+ *     findAdjacentSlots 는 world X 차로만 검사 → far cell 도 reach 안으로 매칭 →
+ *     Crane.moveTo 의 carriagePosition clamp 끝점 박힘 → carriage narrow.
+ *
+ * 가설 확인 path — 두 식 비교:
+ *   (legacy) xOk = |pos.x - cx| <= xHalf;  zOk = |pos.z - cz| <= zHalf
+ *   (fix)    railLocalX = dx*cos + dz*sin;  railLocalZ = -dx*sin + dz*cos
+ *            xOk = |railLocalX| <= xHalf;  zOk = |railLocalZ| <= zHalf
+ *
+ * rotation = 0 → 두 식 결과 동일 (StorageRack 정상 설명).
+ * rotation = π/2 → 두 식 결과 다름 (RackGrid narrow 설명).
+ */
+
+import 'should'
+
+function legacyReach(opts: {
+  pos: { x: number; z: number }
+  crane: { x: number; z: number }
+  xHalf: number; zHalf: number
+}): { xOk: boolean; zOk: boolean; matched: boolean } {
+  const dx = Math.abs(opts.pos.x - opts.crane.x)
+  const dz = Math.abs(opts.pos.z - opts.crane.z)
+  const xOk = dx <= opts.xHalf
+  const zOk = dz <= opts.zHalf
+  return { xOk, zOk, matched: xOk && zOk }
+}
+
+function fixReach(opts: {
+  pos: { x: number; z: number }
+  crane: { x: number; z: number }
+  rotation: number
+  xHalf: number; zHalf: number
+}): { railLocalX: number; railLocalZ: number; xOk: boolean; zOk: boolean; matched: boolean } {
+  const dx = opts.pos.x - opts.crane.x
+  const dz = opts.pos.z - opts.crane.z
+  const cos = Math.cos(opts.rotation)
+  const sin = Math.sin(opts.rotation)
+  const railLocalX = dx * cos + dz * sin
+  const railLocalZ = -dx * sin + dz * cos
+  const xOk = Math.abs(railLocalX) <= opts.xHalf
+  const zOk = Math.abs(railLocalZ) <= opts.zHalf
+  return { railLocalX, railLocalZ, xOk, zOk, matched: xOk && zOk }
+}
+
+describe('rotation = 0 (StorageRack 모델 가정) — legacy 와 fix 동일 동작', () => {
+  it('cell 이 X reach 안 + Z reach 안 → 둘 다 matched', () => {
+    const legacy = legacyReach({ pos: { x: 100, z: 50 }, crane: { x: 0, z: 0 }, xHalf: 200, zHalf: 100 })
+    const fix = fixReach({ pos: { x: 100, z: 50 }, crane: { x: 0, z: 0 }, rotation: 0, xHalf: 200, zHalf: 100 })
+    legacy.matched.should.be.true()
+    fix.matched.should.be.true()
+  })
+
+  it('cell 이 X reach 밖 → 둘 다 not matched', () => {
+    const legacy = legacyReach({ pos: { x: 500, z: 50 }, crane: { x: 0, z: 0 }, xHalf: 200, zHalf: 100 })
+    const fix = fixReach({ pos: { x: 500, z: 50 }, crane: { x: 0, z: 0 }, rotation: 0, xHalf: 200, zHalf: 100 })
+    legacy.matched.should.be.false()
+    fix.matched.should.be.false()
+  })
+
+  it('cell 이 Z reach 밖 → 둘 다 not matched', () => {
+    const legacy = legacyReach({ pos: { x: 100, z: 800 }, crane: { x: 0, z: 0 }, xHalf: 200, zHalf: 100 })
+    const fix = fixReach({ pos: { x: 100, z: 800 }, crane: { x: 0, z: 0 }, rotation: 0, xHalf: 200, zHalf: 100 })
+    legacy.matched.should.be.false()
+    fix.matched.should.be.false()
+  })
+})
+
+describe('rotation = π/2 (RackGrid 모델 — diag 의 확정 값) — legacy 와 fix 결과 다름', () => {
+  // 사용자 모델 의 *_rail X axis 가 world Z axis* (rotation π/2 회전).
+  // 즉 carriage 의 실 운동 = world Z 방향.
+
+  it('cell 이 rail axis (= world Z) 따라 reach 안 → fix 만 정확히 matched', () => {
+    // cell 의 world Z 가 crane Z 와 가까움 (= rail 안). world X 차 작음.
+    // 사용자 의도: matched. legacy 와 fix 둘 다 matched 일 것 (X reach 안).
+    const legacy = legacyReach({ pos: { x: 50, z: 100 }, crane: { x: 0, z: 0 }, xHalf: 200, zHalf: 100 })
+    const fix = fixReach({ pos: { x: 50, z: 100 }, crane: { x: 0, z: 0 }, rotation: Math.PI / 2, xHalf: 200, zHalf: 100 })
+    legacy.matched.should.be.true()
+    fix.matched.should.be.true()
+  })
+
+  it('cell 이 rail axis 따라 reach 밖 (= world Z 차 큼) → fix 만 not matched', () => {
+    // 사용자 의도: cell 의 world Z 가 crane Z 와 멀음 = rail 밖 → NOT matched.
+    // legacy: world Z 차 = 800 > zHalf(100) → not matched. fix 도 not matched. 둘 다 정확.
+    const legacy = legacyReach({ pos: { x: 50, z: 800 }, crane: { x: 0, z: 0 }, xHalf: 200, zHalf: 100 })
+    const fix = fixReach({ pos: { x: 50, z: 800 }, crane: { x: 0, z: 0 }, rotation: Math.PI / 2, xHalf: 200, zHalf: 100 })
+    legacy.matched.should.be.false()
+    fix.matched.should.be.false()
+  })
+
+  it('★ 결정적 시나리오 ★ cell 이 *world X 방향* 으로 매우 멀음 + world Z 가까움 — legacy 는 *not matched* (잘못), fix 는 *matched* (정확)', () => {
+    // rail X axis = world Z 인 모델. cell 의 world Z = 50 (rail 안), world X = 600 (멀음).
+    // 사용자 의도: rail X axis 의 perpendicular (= world X) 차이는 *_fork reach (zHalf=100)*
+    // 안 이어야 함. 600 > 100 → 사용자 의도 = NOT matched.
+    //
+    // legacy: |dx|=600 > xHalf(200) → not matched.
+    // fix:    railLocalX = 0*0 + 50*1 = 50 (rail 안). railLocalZ = -600*1 + 50*0 = -600.
+    //         |railLocalZ| = 600 > zHalf(100) → not matched.
+    // 둘 다 not matched — 일치하나 *_왜* 의 path 다름.
+    const legacy = legacyReach({ pos: { x: 600, z: 50 }, crane: { x: 0, z: 0 }, xHalf: 200, zHalf: 100 })
+    const fix = fixReach({ pos: { x: 600, z: 50 }, crane: { x: 0, z: 0 }, rotation: Math.PI / 2, xHalf: 200, zHalf: 100 })
+    legacy.matched.should.be.false()
+    fix.matched.should.be.false()
+    // 핵심 — fix 의 railLocalX 는 작은 값 (50, rail 안), railLocalZ 가 큰 값 (-600, fork 밖).
+    fix.railLocalX.should.equal(50)
+    fix.railLocalZ.should.equal(-600)
+  })
+
+  it('★ narrow source 의 결정적 증거 ★ cell 의 world Z 가 매우 멀음 + world X 안 — legacy 는 *X reach 안* 으로 매칭, fix 는 *rail axis 밖* 으로 reject', () => {
+    // 사용자 모델 의 *_rotation π/2* — rail X axis = world Z. cell 의 world Z = 700
+    // (rail 의 X axis 따라 매우 멀음 — 사용자 의도 NOT matched, *_rail 밖*).
+    // 그러나 world X 는 0 (X reach 안). legacy 는 X reach 통과 → matched (잘못).
+    // fix: railLocalX = 0*0 + 700*1 = 700. |railLocalX| = 700 > xHalf(200) → not matched. 정확.
+    const legacy = legacyReach({ pos: { x: 0, z: 700 }, crane: { x: 0, z: 0 }, xHalf: 200, zHalf: 1500 })
+    const fix = fixReach({ pos: { x: 0, z: 700 }, crane: { x: 0, z: 0 }, rotation: Math.PI / 2, xHalf: 200, zHalf: 1500 })
+    // legacy 의 zHalf 를 일부러 크게 — Z 검사 통과시키고 X 검사 통과 여부 만 보기 위함.
+    legacy.matched.should.be.true()    // ← legacy 의 잘못된 매칭 (실 사용자 narrow 의 source)
+    fix.matched.should.be.false()      // ← fix 의 정확한 reject
+    fix.railLocalX.should.equal(700)
+  })
+})
+
+describe('useBoundScope = true (X 무관) — 진짜 *narrow source* 검증', () => {
+  // 기존 코드: useBoundScope = true 시 xOk = true (X 무관). 의도 = "rail 끝까지 reach".
+  // 실 결과: rail 의 *_perpendicular axis (= fork 방향)* 만 검사 → rail axis 따라 *_무한 cell*
+  // 매칭 → Crane.moveTo 가 그 cell 의 railLocalX 값 (큰 음수/양수) 으로 clamp 끝점 박힘.
+
+  function boundScopeReach(opts: {
+    pos: { x: number; z: number }; crane: { x: number; z: number }
+    rotation: number; zHalf: number
+  }): { matched: boolean; railLocalX: number } {
+    const dx = opts.pos.x - opts.crane.x
+    const dz = opts.pos.z - opts.crane.z
+    const cos = Math.cos(opts.rotation)
+    const sin = Math.sin(opts.rotation)
+    const railLocalX = dx * cos + dz * sin
+    const railLocalZ = -dx * sin + dz * cos
+    const xOk = true   // ← useBoundScope = true 시 X 무관
+    const zOk = Math.abs(opts.pos.z - opts.crane.z) <= opts.zHalf   // ← 기존: world Z 차로만 검사
+    return { matched: xOk && zOk, railLocalX }
+  }
+
+  it('rotation π/2 + bound 모델 — 멀리 떨어진 cell 도 매칭됨 → Crane.moveTo 에서 railLocalX 큰 값', () => {
+    // cell 의 world Z = 50 (Z reach 안), world X = 1000 (매우 멀음).
+    const r = boundScopeReach({
+      pos: { x: 1000, z: 50 }, crane: { x: 0, z: 0 },
+      rotation: Math.PI / 2, zHalf: 100
+    })
+    r.matched.should.be.true()
+    // Crane.moveTo 의 railLocalX = dx*cos + dz*sin = 1000*0 + 50*1 = 50. 작은 값 정상.
+    r.railLocalX.should.be.approximately(50, 1e-9)
+    // 즉 이 시나리오 는 *_narrow source 아님*. legacy 의 bound scope 가 X 무관이라도
+    // railLocalX 가 작아서 clamp 안 됨.
+  })
+
+  it('★ 실 narrow source ★ rotation π/2 + cell 의 *world Z 가 멀음* (rail X 따라 멀음) + world Z 차 > zHalf 일 때', () => {
+    // 사용자 모델 의 *_여러 RackGrid 의 *_far row*. cell 의 world Z 가 *_특정 row 의 Y*.
+    // 같은 RackGrid 안 *_여러 row 의 cell* 의 Y variance > zHalf.
+    // 단, 이 시나리오 = Z 검사 통과 못 함 → not matched. narrow source 아님.
+    const r = boundScopeReach({
+      pos: { x: 50, z: 800 }, crane: { x: 0, z: 0 },
+      rotation: Math.PI / 2, zHalf: 100
+    })
+    r.matched.should.be.false()
+  })
+
+  it('rotation = π/2 + RackGrid 의 *aisle row* cell — world Z 가 crane.z 근처 (reach 안), world X 가 col 따라 다양', () => {
+    // RackGrid 의 aisle row 만 매칭 — 같은 row 의 여러 col cell.
+    // 각 col 의 world X 가 다양 → railLocalX = dx*cos + dz*sin = 0 + dz*1 = dz (= 0 근처) 동일!
+    // = 모든 col 의 cell 이 *_같은 railLocalX (≈ 0)* → carriage 가 *_같은 carriagePosition* visit → narrow.
+    //
+    // 사용자 의도: carriage 가 *_col 따라 다양한 X visit*. 그러려면 *_rail X axis = world X*
+    // (rotation = 0). 그러나 사용자 모델 = rotation π/2 → rail X = world Z → col variance 영향 없음.
+    const cells = [
+      { x: -200, z: 50 },
+      { x: 0, z: 50 },
+      { x: 200, z: 50 },
+      { x: 400, z: 50 }
+    ]
+    const railLocalXs = cells.map(pos =>
+      boundScopeReach({ pos, crane: { x: 0, z: 0 }, rotation: Math.PI / 2, zHalf: 100 }).railLocalX
+    )
+    // 모든 col 의 railLocalX 가 *_같음* (= 50). carriage variance 0!
+    for (const v of railLocalXs) v.should.be.approximately(50, 1e-9)
+    // variance check — 최대 ~floating noise 만, 의미있는 variance 0.
+    const variance = Math.max(...railLocalXs) - Math.min(...railLocalXs)
+    variance.should.be.lessThan(1e-9)
+    // ⇒ 사용자 보고 narrow ✓. 진짜 source = 모델의 crane.rotation 이 aisle 방향과 어긋남.
+  })
+})
+
+describe('★ 결론 ★ RackGrid 모델 narrow 의 진짜 source', () => {
+  it('rotation = π/2 + cell 분포 가 *col 방향 (world X)* — rail X axis (= world Z) 와 직각 → carriage variance 0', () => {
+    // 같은 row 의 여러 col cell 들은 *_world X 만 다양*, world Z 동일.
+    // rail X = world Z (rotation π/2). 즉 cell 의 carriage 도달 위치 = railLocalX = dz (동일).
+    // ⇒ carriage 가 한 점만 visit. = 사용자 보고 narrow.
+    const dzs = [50, 50, 50, 50]   // 모든 cell 의 dz 동일 (= 같은 row)
+    new Set(dzs).size.should.equal(1)   // variance 0
+  })
+
+  it('rotation = 0 + cell 분포 가 *col 방향* — rail X axis (= world X) 와 평행 → carriage variance 큼', () => {
+    // 같은 row 의 여러 col cell — *_world X 다양*. rail X = world X. railLocalX = dx (다양).
+    const cells = [
+      { x: -200, z: 50 },
+      { x: 0, z: 50 },
+      { x: 200, z: 50 },
+      { x: 400, z: 50 }
+    ]
+    const cos = 1, sin = 0   // rotation 0
+    const railLocalXs = cells.map(p => p.x * cos + p.z * sin)
+    new Set(railLocalXs).size.should.equal(4)   // variance 큼
+    // ⇒ StorageRack (rotation = 0) 정상 동작 설명.
+  })
+})

package/test/test-rack-grid-3d-alignment.ts

@@ -0,0 +1,235 @@
+/*
+ * RackGrid — anchor / stock / carrier 의 *실제 3D world position 일치* 검증.
+ *
+ * 사용자 보고: pick 시 carrier 가 *anchor (= fork 가 가는 자리)* 와 다른 위치에
+ * 그려져 fork 가 빈 포크질. 식 자체가 어디서 어긋나는지를 *실 Three.js
+ * scene graph* 로 직접 검증.
+ *
+ *   1. rack.object3d (THREE.Group) 만들기
+ *   2. anchor / stock / carrier 를 각각 *그 자식* 으로 추가
+ *   3. 각 식 (코드 발췌) 으로 position set 후 matrixWorld 비교
+ *
+ *  세 값이 모든 (col, row, shelf) 에서 동일하면 식 자체는 정확. 어긋나면 *어느
+ *  식이 잘못된지* 즉시 식별.
+ */
+
+import 'should'
+import * as THREE from 'three'
+
+// ── 식 발췌 — RackGrid 의 실제 코드와 동일 ─────────────────────────────────
+
+interface RackParams {
+  width: number       // 3D X
+  height: number      // 3D Z (front-back) = state.height = 2D bounds height
+  depth: number       // 3D Y (vertical) = state.depth
+  cols: number
+  rows: number
+  shelves: number
+  shelfBase: number
+}
+
+function derived(rp: RackParams) {
+  const bayW = rp.width / rp.cols
+  const bayD = rp.height / rp.rows
+  const shelfZone = rp.depth - rp.shelfBase
+  const cellY = shelfZone / rp.shelves
+  const baseY = -rp.depth / 2
+  const shelfBaseY = baseY + rp.shelfBase
+  const stockD = cellY * 0.7
+  return { bayW, bayD, shelfZone, cellY, baseY, shelfBaseY, stockD }
+}
+
+// anchor 식 — rack-grid.ts getSlotAttachObject3d (line 1346-1349)
+function anchorPos(col: number, row: number, shelf: number, rp: RackParams) {
+  const { bayW, bayD, cellY, shelfBaseY, stockD } = derived(rp)
+  return {
+    x: (col - rp.cols / 2 + 0.5) * bayW,
+    y: shelfBaseY + shelf * cellY + stockD / 2,
+    z: (row - rp.rows / 2 + 0.5) * bayD
+  }
+}
+
+// stock 식 — rack-grid-3d.ts matrixFor (line 358-363, cy 식은 line 280 부근의 동일)
+function stockPos(col: number, row: number, shelf: number, rp: RackParams) {
+  const { bayW, bayD, cellY, shelfBaseY, stockD } = derived(rp)
+  return {
+    x: (col - rp.cols / 2 + 0.5) * bayW,
+    y: shelfBaseY + shelf * cellY + stockD / 2,
+    z: (row - rp.rows / 2 + 0.5) * bayD
+  }
+}
+
+// carrier 식 — rack-grid.ts obtainCarrier 의 *2D state.left/top → 3D world* 변환.
+// 내 가정: parent (RackGrid) 의 *2D bounds center* 가 *3D origin*. 즉
+//   3D X = state.left + carrierW/2 - parent.width/2 = cellCenterInnerX - rackWidth/2
+//   3D Z = state.top + carrierH/2 - parent.height/2 = cellCenterInnerY - rackHeight/2
+// 단 *2D Y → 3D Z 부호* 가 +/- 어느 쪽인지 things-scene 컨벤션 따라.
+function carrierPos_assumeY_to_PlusZ(col: number, row: number, shelf: number, rp: RackParams) {
+  const { bayW, bayD, cellY, shelfBaseY, stockD } = derived(rp)
+  const cellCenterInnerX = (col + 0.5) * bayW
+  const cellCenterInnerY = (row + 0.5) * bayD
+  return {
+    x: cellCenterInnerX - rp.width / 2,
+    y: shelfBaseY + shelf * cellY + stockD / 2,   // anchor 와 동일 (carrier.depth 가 stockD 인 가정)
+    z: cellCenterInnerY - rp.height / 2
+  }
+}
+
+// 부호 반대 가설 — 2D Y → 3D -Z
+function carrierPos_assumeY_to_MinusZ(col: number, row: number, shelf: number, rp: RackParams) {
+  const { cellY, shelfBaseY, stockD, bayW, bayD } = derived(rp)
+  const cellCenterInnerX = (col + 0.5) * bayW
+  const cellCenterInnerY = (row + 0.5) * bayD
+  return {
+    x: cellCenterInnerX - rp.width / 2,
+    y: shelfBaseY + shelf * cellY + stockD / 2,
+    z: rp.height / 2 - cellCenterInnerY    // 부호 반전
+  }
+}
+
+// ── Helper — 실 Three.js Group 안에 3 객체 add 후 matrixWorld 비교 ────────────
+
+function compareWorld(rp: RackParams, col: number, row: number, shelf: number) {
+  const rackObj = new THREE.Group()
+  rackObj.position.set(0, 0, 0)
+  rackObj.updateMatrixWorld(true)
+
+  const a = anchorPos(col, row, shelf, rp)
+  const s = stockPos(col, row, shelf, rp)
+  const c1 = carrierPos_assumeY_to_PlusZ(col, row, shelf, rp)
+  const c2 = carrierPos_assumeY_to_MinusZ(col, row, shelf, rp)
+
+  const anchorObj = new THREE.Object3D()
+  anchorObj.position.set(a.x, a.y, a.z)
+  rackObj.add(anchorObj)
+
+  const stockObj = new THREE.Object3D()
+  stockObj.position.set(s.x, s.y, s.z)
+  rackObj.add(stockObj)
+
+  const carrier1Obj = new THREE.Object3D()
+  carrier1Obj.position.set(c1.x, c1.y, c1.z)
+  rackObj.add(carrier1Obj)
+
+  const carrier2Obj = new THREE.Object3D()
+  carrier2Obj.position.set(c2.x, c2.y, c2.z)
+  rackObj.add(carrier2Obj)
+
+  rackObj.updateMatrixWorld(true)
+
+  const aw = new THREE.Vector3()
+  const sw = new THREE.Vector3()
+  const c1w = new THREE.Vector3()
+  const c2w = new THREE.Vector3()
+  anchorObj.getWorldPosition(aw)
+  stockObj.getWorldPosition(sw)
+  carrier1Obj.getWorldPosition(c1w)
+  carrier2Obj.getWorldPosition(c2w)
+
+  return { aw, sw, c1w, c2w }
+}
+
+// ── Tests ──────────────────────────────────────────────────────────────────
+
+describe('RackGrid Real 3D: anchor / stock / carrier world position 일치', () => {
+  const rp: RackParams = {
+    width: 1000, height: 600, depth: 2000,
+    cols: 5, rows: 3, shelves: 4, shelfBase: 0
+  }
+
+  it('anchor 와 stock 은 *모든 (col,row,shelf)* 에서 동일 world position', () => {
+    for (let col = 0; col < rp.cols; col++) {
+      for (let row = 0; row < rp.rows; row++) {
+        for (let shelf = 0; shelf < rp.shelves; shelf++) {
+          const { aw, sw } = compareWorld(rp, col, row, shelf)
+          aw.x.should.be.approximately(sw.x, 1e-9, `col=${col} row=${row} shelf=${shelf}`)
+          aw.y.should.be.approximately(sw.y, 1e-9, `col=${col} row=${row} shelf=${shelf}`)
+          aw.z.should.be.approximately(sw.z, 1e-9, `col=${col} row=${row} shelf=${shelf}`)
+        }
+      }
+    }
+  })
+
+  it('carrier (2D Y → 3D +Z 가정) — anchor 와 동일 world position', () => {
+    // 사용자가 *현재 코드* 의 식. fork 가 가는 자리(anchor) 와 carrier 가 같은 곳에
+    // 있어야 정상. 이 테스트 통과 = 식 자체 정확. 그러면 사용자 보고의 어긋남은
+    // *things-scene 의 *2D → 3D 변환* 이 *우리 가정과 다름* 시사.
+    for (let col = 0; col < rp.cols; col++) {
+      for (let row = 0; row < rp.rows; row++) {
+        for (let shelf = 0; shelf < rp.shelves; shelf++) {
+          const { aw, c1w } = compareWorld(rp, col, row, shelf)
+          aw.x.should.be.approximately(c1w.x, 1e-9, `+Z col=${col} row=${row} shelf=${shelf}`)
+          aw.y.should.be.approximately(c1w.y, 1e-9, `+Z col=${col} row=${row} shelf=${shelf}`)
+          aw.z.should.be.approximately(c1w.z, 1e-9, `+Z col=${col} row=${row} shelf=${shelf}`)
+        }
+      }
+    }
+  })
+
+  it('carrier (2D Y → 3D -Z 가정) — Z 좌표가 anchor 와 *반대 부호*', () => {
+    // 만약 things-scene 의 변환 컨벤션이 이쪽이라면 *내 obtainCarrier 식의 Z* 가
+    // *anchor 와 반대* — fork 가 anchor 위치 (= stock 자리) 로 오는데 carrier 는
+    // *반대 측 Z* 에 그려짐. 사용자 보고와 일치하는 가설.
+    for (let col = 0; col < rp.cols; col++) {
+      for (let row = 0; row < rp.rows; row++) {
+        const { aw, c2w } = compareWorld(rp, col, row, 0)
+        if (row === rp.rows / 2 - 0.5 || row === Math.floor(rp.rows / 2)) {
+          // 중앙 row 는 Z=0 이라 부호 무관 — skip
+          continue
+        }
+        // Z 부호 반대 — anchor.z 와 c2w.z 의 *합이 0* (대칭)
+        ;(aw.z + c2w.z).should.be.approximately(0, 1e-9,
+          `row=${row}: anchor.z=${aw.z}, carrier(-Z).z=${c2w.z}`)
+      }
+    }
+  })
+
+  it('row 별 anchor.z 값 명시 — row=0 가 *-Z (앞)*, row=N-1 가 *+Z (뒤)*', () => {
+    const { aw: aw0 } = compareWorld(rp, 0, 0, 0)
+    const { aw: awLast } = compareWorld(rp, 0, rp.rows - 1, 0)
+    aw0.z.should.be.lessThan(0)
+    awLast.z.should.be.greaterThan(0)
+    // bayD = height / rows = 200
+    // row 0: (0 - 1.5 + 0.5) * 200 = -200
+    // row 2: (2 - 1.5 + 0.5) * 200 = +200
+    aw0.z.should.be.approximately(-200, 1e-9)
+    awLast.z.should.be.approximately(200, 1e-9)
+  })
+})
+
+// ── 사용자 보고 *fork 가 뒤로 나감* 가설 분리 ─────────────────────────────────
+
+describe('RackGrid: fork 진입 방향 가설 분리', () => {
+  /*
+   * 위 테스트의 두 carrier 식 결과로 본 분리:
+   *
+   *  (A) anchor / stock / carrier(+Z) 모두 동일 world  → 모두 식 정확.
+   *      사용자 보고의 어긋남은 *식 외* 원인:
+   *        - things-scene 의 *2D → 3D 변환 부호* 가 +Z 가 아닌 -Z (= carrier(-Z) 가
+   *          실제 carrier 위치). 그러면 *carrier 가 anchor 반대* — fork 빈 공간 + 뒤로.
+   *          → fix: rack-grid.ts 의 cellCenterInnerY 부호 반전.
+   *        - 또는 things-scene 변환이 +Z 정확 → *fork 의 *진입 face* 가 *crane 위치*
+   *          따라 자동 결정 = 시뮬레이션 *crane 의 RackGrid 측 위치* 가 *fork 진입
+   *          반대 방향*. *코드 fix 외 영역*.
+   *
+   *  (B) anchor != stock 또는 anchor != carrier → 식 자체 잘못. 수정 대상 분명.
+   */
+  it('진단 출력 — row=0 ~ row=N-1 의 anchor.z / carrier(+Z).z / carrier(-Z).z', () => {
+    const rp: RackParams = {
+      width: 1000, height: 600, depth: 2000,
+      cols: 5, rows: 3, shelves: 4, shelfBase: 0
+    }
+    const rows: Array<{ row: number; anchorZ: number; carrierPlusZ: number; carrierMinusZ: number }> = []
+    for (let row = 0; row < rp.rows; row++) {
+      const { aw, c1w, c2w } = compareWorld(rp, 0, row, 0)
+      rows.push({
+        row,
+        anchorZ: Math.round(aw.z),
+        carrierPlusZ: Math.round(c1w.z),
+        carrierMinusZ: Math.round(c2w.z)
+      })
+    }
+    console.table(rows)
+    rows.length.should.equal(rp.rows)
+  })
+})