@operato/scene-storage 10.0.0-beta.40 → 10.0.0-beta.42

package/test/test-mover-concurrent-bug.ts

@@ -0,0 +1,304 @@
+/*
+ * 실 production 결함 재현 — *동시 pickAndPlace* 의 mover 충돌.
+ *
+ * 사용자가 보고한 회귀 패턴 (transfer panel):
+ *   - Phase 10 ✓ rack → crane (첫 pick 성공)
+ *   - Phase 3 ✗ crane → crane all-slots-full (자기 자신에게 transfer 시도)
+ *   - Phase 3 ✗ [model-layer] → crane all-slots-full (다른 carrier 가 또 시도)
+ *   - Phase 1 ✗ crane → slot-target cannot-receive (dest 가 점유)
+ *   - 크레인이 멈춰버림
+ *
+ * 가설: 두 개의 pickAndPlace 가 *동시 진행* 중. 한쪽은 사용자 script, 다른 한쪽은
+ * 정체불명. 두 카리어가 같은 crane forks slot 을 두고 경쟁 → 충돌.
+ *
+ * 이 테스트는 *그 시나리오를 재현* 해 *실제로 어떻게 깨지는지* 드러내는 게 목표.
+ * 통과하면 multi-mover 가 안전, 실패하면 framework / Mover 의 race condition 노출.
+ */
+
+import 'should'
+
+// ── 최소 Mover-like (Plan A 의 슬롯 컨트랙 + capacity 추적) ────────────────────
+
+interface SlotDef { id: string; maxCount: number }
+
+class FakeCrane {
+  slots: SlotDef[] = [{ id: 'forks', maxCount: 1 }]
+  components: any[] = []
+  _events: any[] = []
+
+  canReceive(_carrier: any): boolean {
+    const fork = this.slots[0]
+    const occupied = this.components.filter(c => c._transferSlotId === fork.id).length
+    return occupied < fork.maxCount
+  }
+
+  async receive(carrier: any): Promise<void> {
+    if (!this.canReceive(carrier)) {
+      this._events.push({ type: 'rejected', reason: 'all-slots-full', carrier })
+      const err: any = new Error('crane forks full')
+      err.reason = 'all-slots-full'
+      throw err
+    }
+    // reparent
+    const op = carrier.parent
+    if (op?.removeComponent) op.removeComponent(carrier)
+    carrier.parent = this
+    this.components.push(carrier)
+    carrier._transferSlotId = 'forks'
+    this._events.push({ type: 'received', carrier })
+  }
+
+  async dispatch(carrier: any, target: any): Promise<void> {
+    if (target.canReceive && !target.canReceive(carrier)) {
+      this._events.push({ type: 'rejected', reason: 'cannot-receive', target })
+      return
+    }
+    delete carrier._transferSlotId
+    if (typeof target.receive === 'function') await target.receive(carrier)
+    this._events.push({ type: 'dispatched', target })
+  }
+
+  // 단순화: pick = source.removeComponent + crane.receive
+  async pick(carrier: any): Promise<void> {
+    if (carrier.parent === this) return    // idempotent
+    await this.receive(carrier)
+  }
+
+  // place = await canReceive polling + dispatch
+  async place(carrier: any, target: any, options: { timeoutMs?: number } = {}): Promise<void> {
+    const timeoutMs = options.timeoutMs ?? 1000   // 짧게 (테스트용)
+    const started = Date.now()
+    while (target.canReceive && !target.canReceive(carrier)) {
+      if (Date.now() - started > timeoutMs) {
+        throw new Error(`place timeout after ${timeoutMs}ms`)
+      }
+      await new Promise(r => setTimeout(r, 10))
+    }
+    await this.dispatch(carrier, target)
+  }
+
+  async pickAndPlace(carrier: any, target: any, options: { timeoutMs?: number } = {}): Promise<void> {
+    await this.pick(carrier)
+    await this.place(carrier, target, options)
+  }
+}
+
+class FakeRack {
+  state: any = { data: [] }
+  components: any[] = []
+
+  records(): any[] { return this.state.data }
+  carrierAt(cellId: string): any {
+    return this.components.find(c => c.placement === 'operation' && c.state?.cellId === cellId)
+  }
+  hasCarrierAt(cellId: string): boolean {
+    return !!this.carrierAt(cellId) || this.records().some((r: any) => r.cellId === cellId)
+  }
+  canReceiveAt(cellId: string): boolean { return !this.hasCarrierAt(cellId) }
+  canReceive(carrier: any): boolean { return this.canReceiveAt(carrier?.state?.cellId ?? '?') }
+
+  addComponent(c: any): void { c.parent = this; this.components.push(c) }
+  removeComponent(c: any): void {
+    const i = this.components.indexOf(c)
+    if (i >= 0) this.components.splice(i, 1)
+    c.parent = null
+  }
+
+  obtainCarrier(cellId: string): any {
+    const existing = this.carrierAt(cellId)
+    if (existing) return existing
+    const idx = this.records().findIndex((r: any) => r.cellId === cellId)
+    if (idx === -1) return null
+    const record = this.records()[idx]
+    const c: any = {
+      placement: 'operation',
+      state: { ...record, cellId },
+      parent: null,
+      dispose() { this._disposed = true }
+    }
+    this.addComponent(c)
+    this.state.data = this.records().filter((_: any, j: number) => j !== idx)
+    return c
+  }
+
+  async receiveAt(cellId: string, carrier: any): Promise<void> {
+    if (!this.canReceiveAt(cellId)) {
+      const err: any = new Error('slot occupied')
+      err.reason = 'slot-occupied'
+      throw err
+    }
+    const p = carrier.parent
+    if (p?.removeComponent) p.removeComponent(carrier)
+    carrier.dispose?.()
+    const rec: any = { cellId, type: carrier.state.type ?? 'parcel', sku: carrier.state.sku }
+    this.state.data = [...this.records(), rec]
+  }
+
+  slotTargetAt(cellId: string): any {
+    const rack = this
+    return {
+      canReceive: (c: any) => rack.canReceiveAt(cellId),
+      receive: (c: any) => rack.receiveAt(cellId, c)
+    }
+  }
+}
+
+// ── Group 1: 동시 pickAndPlace 시나리오 ─────────────────────────────────────
+
+describe('Bug-finder: 동시 pickAndPlace', () => {
+
+  it('REPRODUCE — 두 carrier 가 *동시에* 같은 crane 으로 pick → 두 번째 reject', async () => {
+    const rack = new FakeRack()
+    rack.state.data = [{ cellId: 'A', sku: 'a' }, { cellId: 'B', sku: 'b' }]
+    const crane = new FakeCrane()
+
+    const cA = rack.obtainCarrier('A')!
+    const cB = rack.obtainCarrier('B')!
+
+    // 동시 pick
+    const results = await Promise.allSettled([
+      crane.pickAndPlace(cA, rack.slotTargetAt('X'), { timeoutMs: 100 }),
+      crane.pickAndPlace(cB, rack.slotTargetAt('Y'), { timeoutMs: 100 })
+    ])
+
+    // 진단:
+    //   - 첫 pick 성공 → crane 에 cA 또는 cB 중 하나
+    //   - 두 번째 pick 은 crane full → reject ('all-slots-full')
+    //   - 이게 사용자가 보는 Phase 3 의 정체
+    const rejected = results.filter(r => r.status === 'rejected')
+    rejected.length.should.be.greaterThanOrEqual(1)
+    // 거부 이유에 'all-slots-full' 또는 timeout 이 보임
+    const reasons = rejected.map(r => (r as PromiseRejectedResult).reason?.reason ?? (r as PromiseRejectedResult).reason?.message)
+    console.log('  → 두 번째 pick 의 reject 사유:', reasons.join(', '))
+  })
+
+  it('REPRODUCE — 첫 pickAndPlace 가 *stuck* (dest 점유) 이면 두 번째도 영향', async () => {
+    const rack = new FakeRack()
+    rack.state.data = [
+      { cellId: 'A', sku: 'a' },
+      { cellId: 'B', sku: 'b' },
+      { cellId: 'X', sku: 'occupier' }   // ← X 점유 (첫 pickAndPlace 의 dest)
+    ]
+    const crane = new FakeCrane()
+
+    const cA = rack.obtainCarrier('A')!
+    const cB = rack.obtainCarrier('B')!
+
+    // 1st: A → X (X 점유라 영원히 stuck → timeout)
+    // 2nd: B → Y (X 와 무관하지만 crane 이 cA 보유 중이라 cB pick fail)
+    const results = await Promise.allSettled([
+      crane.pickAndPlace(cA, rack.slotTargetAt('X'), { timeoutMs: 50 }),
+      crane.pickAndPlace(cB, rack.slotTargetAt('Y'), { timeoutMs: 50 })
+    ])
+
+    const failures = results.filter(r => r.status === 'rejected')
+    failures.length.should.be.greaterThanOrEqual(1)
+    console.log('  → 사용자 보고 사례 재현:', failures.map(f => (f as PromiseRejectedResult).reason?.reason ?? (f as PromiseRejectedResult).reason?.message))
+  })
+})
+
+// ── Group 2: 사용자 시나리오 정확 재현 ─────────────────────────────────────
+
+describe('Bug-finder: 사용자 보고 시나리오', () => {
+
+  it('REPRODUCE — original parcel (model-layer) + transient (obtainCarrier) 동시 pickAndPlace', async () => {
+    const rack = new FakeRack()
+    rack.state.data = [
+      { cellId: '0-0-5' },                          // 사용자 transient 의 source
+      { cellId: '2-0-3', sku: 'occupier' }          // dest — *이미 점유*
+    ]
+    const modelLayer: any = {
+      components: [] as any[],
+      removeComponent(c: any) {
+        const i = this.components.indexOf(c)
+        if (i >= 0) this.components.splice(i, 1)
+        c.parent = null
+      }
+    }
+    const originalParcel: any = {
+      placement: 'operation',
+      state: { id: 'parcel', type: 'parcel' },
+      parent: modelLayer,
+      dispose() { this._disposed = true }
+    }
+    modelLayer.components.push(originalParcel)
+
+    const crane = new FakeCrane()
+    const transient = rack.obtainCarrier('0-0-5')!
+
+    // 두 pickAndPlace 동시 실행 — 사용자 환경에서 무엇 fire 되는지 모르지만 *둘 다 fire 됐다고
+    // 가정* 했을 때 어떤 일이 벌어지는지 재현.
+    const r1 = crane.pickAndPlace(transient, rack.slotTargetAt('2-0-3'), { timeoutMs: 50 })
+    const r2 = crane.pickAndPlace(originalParcel, rack.slotTargetAt('0-0-6'), { timeoutMs: 50 })
+
+    const results = await Promise.allSettled([r1, r2])
+
+    // 진단:
+    //   - 첫 pick (transient 또는 originalParcel) 성공 → crane 에 들어감
+    //   - 두 번째 pick 시도 → crane full → reject (all-slots-full)
+    //   - 첫 place 시도 → dest '2-0-3' 점유 → timeout (cannot-receive 영구)
+    //   - 결과: crane 에 carrier 그대로 남음, 두 pickAndPlace 다 fail
+
+    const failed = results.filter(r => r.status === 'rejected')
+    console.log('  → 결과:', results.map(r => r.status === 'rejected'
+      ? `REJECTED(${(r as PromiseRejectedResult).reason?.reason ?? (r as PromiseRejectedResult).reason?.message})`
+      : 'FULFILLED'
+    ).join(', '))
+
+    failed.length.should.be.greaterThanOrEqual(1)
+    crane.components.length.should.equal(1)   // ← *한 carrier 가 crane 에 stuck*
+    // ↑ 이게 사용자 환경의 "크레인이 멈춤" 의 직접 원인
+  })
+})
+
+// ── Group 3: timeout 으로 stuck 자동 복구 검증 ───────────────────────────────
+
+describe('Bug-finder: place timeout 동작', () => {
+
+  it('FIX VERIFY — dest 가 점유여도 timeout 후 throw, mover 가 풀림', async () => {
+    const rack = new FakeRack()
+    rack.state.data = [
+      { cellId: 'A', sku: 'a' },
+      { cellId: 'X', sku: 'occupied-forever' }
+    ]
+    const crane = new FakeCrane()
+    const c = rack.obtainCarrier('A')!
+
+    const started = Date.now()
+    let thrown: any = null
+    try {
+      await crane.pickAndPlace(c, rack.slotTargetAt('X'), { timeoutMs: 100 })
+    } catch (e) {
+      thrown = e
+    }
+    const elapsed = Date.now() - started
+
+    thrown.should.not.be.null()
+    elapsed.should.be.greaterThanOrEqual(100)
+    elapsed.should.be.lessThan(500)   // timeout 정확히 fire
+    // 단 — carrier 는 crane 에 그대로 남음 (timeout 후 정리 안 함)
+    crane.components.length.should.equal(1)
+    console.log('  → timeout 후 carrier 가 crane 에 잔존:', crane.components.length, '개')
+    // ↑ 결함 발견: timeout 으로 throw 해도 carrier 가 crane fork 위에 영구. 추가 fix 필요.
+  })
+
+  it('FIX REQUIRED — timeout 후 carrier 가 *어디로 가야* 하는가? (현재: 안 가서 mover lock 잔존)', async () => {
+    const rack = new FakeRack()
+    rack.state.data = [{ cellId: 'A' }, { cellId: 'X', sku: 'blocker' }]
+    const crane = new FakeCrane()
+    const c = rack.obtainCarrier('A')!
+
+    try {
+      await crane.pickAndPlace(c, rack.slotTargetAt('X'), { timeoutMs: 50 })
+    } catch {}
+
+    // 다음 pickAndPlace 시도 — crane 이 풀려 있어야 새 작업 받을 수 있는데...
+    const rack2Records = rack.state.data.length
+    // 사실: crane.components.length === 1 → 다음 pick 은 'all-slots-full' 로 실패
+    crane.components.length.should.equal(1)
+    crane.canReceive({}).should.be.false()   // ← *진정한 결함*: timeout 후에도 풀이라고 인식
+
+    console.log('  → 후속 작업 차단됨. crane.canReceive = false (carrier 가 forks 에 stuck)')
+    console.log('  → 해결책: timeout 시 carrier 를 *원래 source 로 환원* 하거나 *명시 dispose*.')
+  })
+})

package/test/test-mover-rollback.ts

@@ -0,0 +1,290 @@
+/*
+ * R3 결함 — Mover.place 가 timeout 으로 fail 한 후 *carrier 가 mover 에 stuck* 되어
+ * mover 가 영구 잠기는 회귀. 해결책은 *rollback*: 실패 시 carrier 를 source 로 복귀,
+ * 또는 mover 에서 떼어 orphan 으로 풀어줌.
+ *
+ * 이 테스트들은 *원하는 동작* 을 명세함 — 현재 (rollback 미구현) 은 fail 해야 함.
+ * 구현 후엔 PASS 하면 fix 검증.
+ */
+
+import 'should'
+import * as THREE from 'three'
+
+class FakeRack {
+  state: any = { data: [] }
+  components: any[] = []
+  records(): any[] { return this.state.data }
+  carrierAt(cellId: string): any {
+    return this.components.find(c => c.placement === 'operation' && c.state?.cellId === cellId)
+  }
+  canReceiveAt(cellId: string, carrier?: any): boolean {
+    if (this.records().some(r => r?.cellId === cellId)) return false
+    const existing = this.carrierAt(cellId)
+    if (existing && existing !== carrier) return false
+    return true
+  }
+  canReceive(carrier: any): boolean {
+    return this.canReceiveAt(carrier?.state?.cellId ?? '?', carrier)
+  }
+  addComponent(c: any): void { c.parent = this; this.components.push(c) }
+  removeComponent(c: any): void {
+    const i = this.components.indexOf(c)
+    if (i >= 0) this.components.splice(i, 1)
+    c.parent = null
+  }
+  obtainCarrier(cellId: string): any {
+    const existing = this.carrierAt(cellId)
+    if (existing) return existing
+    const idx = this.records().findIndex(r => r?.cellId === cellId)
+    if (idx === -1) return null
+    const record = this.records()[idx]
+    const c: any = {
+      placement: 'operation',
+      state: { ...record, cellId },
+      parent: null,
+      _realObject: { object3d: new THREE.Group() },
+      dispose() { this._disposed = true; this._realObject.object3d.clear() }
+    }
+    this.addComponent(c)
+    this.state.data = this.records().filter(r => r?.cellId !== cellId)
+    return c
+  }
+  async receiveAt(cellId: string, carrier: any): Promise<void> {
+    if (!this.canReceiveAt(cellId, carrier)) {
+      const err: any = new Error('slot occupied')
+      err.reason = 'slot-occupied'
+      throw err
+    }
+    const p = carrier.parent
+    if (p?.removeComponent) p.removeComponent(carrier)
+    const obj = carrier._realObject?.object3d
+    if (obj?.parent?.remove) obj.parent.remove(obj)
+    carrier.dispose?.()
+    const remaining = this.records().filter(r => r?.cellId !== cellId)
+    this.state.data = [...remaining, { cellId, type: carrier.state.type ?? 'parcel', sku: carrier.state.sku }]
+  }
+  slotTargetAt(cellId: string): any {
+    const rack = this
+    return {
+      slotId: cellId,
+      holder: rack,
+      canReceive: (c: any) => rack.canReceiveAt(cellId, c),
+      receive: (c: any) => rack.receiveAt(cellId, c)
+    }
+  }
+  // Optional Transferable.receive — 사용 안 함 (slot 기반 holder 의 source rollback 은
+  // slotTargetAt 로 시도)
+}
+
+// Mover with rollback — *제안된* 동작
+class FakeCrane {
+  components: any[] = []
+  forkObject3d = new THREE.Object3D()
+  constructor() { this.forkObject3d.name = 'crane-fork' }
+
+  canReceive(_carrier: any): boolean {
+    return this.components.filter(c => c._transferSlotId === 'forks').length < 1
+  }
+  async receive(carrier: any): Promise<void> {
+    if (!this.canReceive(carrier)) {
+      const err: any = new Error('crane full')
+      err.reason = 'all-slots-full'
+      throw err
+    }
+    const op = carrier.parent
+    if (op?.removeComponent) op.removeComponent(carrier)
+    carrier.parent = this
+    this.components.push(carrier)
+    carrier._transferSlotId = 'forks'
+    const obj = carrier._realObject?.object3d
+    if (obj) {
+      if (obj.parent?.remove) obj.parent.remove(obj)
+      this.forkObject3d.attach(obj)
+      obj.position.set(0, 0, 0)
+    }
+  }
+  removeComponent(c: any): void {
+    const i = this.components.indexOf(c)
+    if (i >= 0) this.components.splice(i, 1)
+    c.parent = null
+  }
+
+  async dispatch(carrier: any, target: any): Promise<void> {
+    if (target.canReceive && !target.canReceive(carrier)) {
+      const err: any = new Error('target rejected')
+      err.reason = 'cannot-receive'
+      throw err
+    }
+    delete carrier._transferSlotId
+    if (typeof target.receive === 'function') await target.receive(carrier)
+  }
+
+  async pick(carrier: any): Promise<void> {
+    if (carrier.parent === this) return
+    await this.receive(carrier)
+  }
+
+  async place(carrier: any, target: any, options: { timeoutMs?: number } = {}): Promise<void> {
+    const timeoutMs = options.timeoutMs ?? 1000
+    const started = Date.now()
+    while (target.canReceive && !target.canReceive(carrier)) {
+      if (Date.now() - started > timeoutMs) {
+        throw new Error(`place timeout after ${timeoutMs}ms`)
+      }
+      await new Promise(r => setTimeout(r, 5))
+    }
+    await this.dispatch(carrier, target)
+  }
+
+  async pickAndPlace(carrier: any, target: any, options: { timeoutMs?: number } = {}): Promise<void> {
+    // *Rollback* — pick 직전 source 캡쳐. place 실패 시 source 로 복귀 시도.
+    const sourceParent: any = carrier.parent
+    const sourceCellId: string | undefined = carrier.state?.cellId
+
+    try {
+      await this.pick(carrier)
+      await this.place(carrier, target, options)
+    } catch (err) {
+      // 실패 시 rollback — carrier 가 *지금 mover 의 child* 면 source 로 돌리거나 풀어줌.
+      if (this.components.includes(carrier)) {
+        const slotTarget = sourceParent?.slotTargetAt?.(sourceCellId)
+        if (slotTarget?.canReceive?.(carrier)) {
+          try {
+            await this.dispatch(carrier, slotTarget)
+          } catch {
+            // 마지막 수단 — mover 에서 detach (orphan)
+            this.removeComponent(carrier)
+            const obj = carrier._realObject?.object3d
+            if (obj?.parent?.remove) obj.parent.remove(obj)
+          }
+        } else {
+          // source 도 못 받으면 orphan
+          this.removeComponent(carrier)
+          const obj = carrier._realObject?.object3d
+          if (obj?.parent?.remove) obj.parent.remove(obj)
+        }
+      }
+      throw err
+    }
+  }
+}
+
+// ── Group 1: place timeout 시 carrier 가 source 로 복귀 ─────────────────────
+
+describe('R3 fix: Mover rollback on place timeout', () => {
+  it('dest 점유로 timeout — carrier 가 *source rack 의 record* 로 복귀', async () => {
+    const rack = new FakeRack()
+    rack.state.data = [
+      { cellId: 'A', sku: 'X' },
+      { cellId: 'B', sku: 'occupied' }
+    ]
+    const crane = new FakeCrane()
+
+    const c = rack.obtainCarrier('A')!
+    rack.records().length.should.equal(1)   // A 빠지고 B 만
+
+    let thrown: any
+    try {
+      await crane.pickAndPlace(c, rack.slotTargetAt('B'), { timeoutMs: 100 })
+    } catch (e) {
+      thrown = e
+    }
+
+    thrown.should.not.be.null()
+    // *Rollback 검증* — carrier 가 다시 source A 의 record 로 복귀
+    rack.records().some((r: any) => r.cellId === 'A').should.be.true()
+    rack.records().some((r: any) => r.cellId === 'B').should.be.true()  // B 도 그대로
+    rack.records().length.should.equal(2)
+
+    // crane 은 풀려있어야 함 — 후속 pickAndPlace 받을 수 있게
+    crane.components.length.should.equal(0)
+    crane.canReceive({}).should.be.true()
+    crane.forkObject3d.children.length.should.equal(0)
+  })
+
+  it('source 도 점유 (record 가 다시 들어옴) → orphan 으로 풀어줌', async () => {
+    const rack = new FakeRack()
+    rack.state.data = [
+      { cellId: 'A', sku: 'X' },
+      { cellId: 'B', sku: 'blocker' }
+    ]
+    const crane = new FakeCrane()
+
+    const c = rack.obtainCarrier('A')!
+    // 외부에서 A 자리에 다른 record push (경쟁 시나리오)
+    rack.state.data = [...rack.state.data, { cellId: 'A', sku: 'sneak' }]
+
+    let thrown: any
+    try {
+      await crane.pickAndPlace(c, rack.slotTargetAt('B'), { timeoutMs: 50 })
+    } catch (e) {
+      thrown = e
+    }
+    thrown.should.not.be.null()
+
+    // source A 가 다시 점유 → carrier 가 그쪽으로 못 가 → orphan 으로 풀어줌
+    crane.components.length.should.equal(0)             // mover 풀림
+    crane.canReceive({}).should.be.true()
+    ;(c.parent === null).should.be.true()                // orphan
+    ;(c._realObject.object3d.parent === null).should.be.true()
+  })
+
+  it('두 번째 pickAndPlace 가 정상 진행 — rollback 후 mover 사용 가능', async () => {
+    const rack = new FakeRack()
+    rack.state.data = [
+      { cellId: 'A' },
+      { cellId: 'B', sku: 'blocker' },
+      { cellId: 'C', sku: 'next' }
+    ]
+    const crane = new FakeCrane()
+
+    // 1st — A → B (실패 예정)
+    const cA = rack.obtainCarrier('A')!
+    try {
+      await crane.pickAndPlace(cA, rack.slotTargetAt('B'), { timeoutMs: 50 })
+    } catch {}
+
+    crane.components.length.should.equal(0)   // rollback OK
+
+    // 2nd — C → 빈 자리 (성공해야 함)
+    const cC = rack.obtainCarrier('C')!
+    await crane.pickAndPlace(cC, rack.slotTargetAt('D'), { timeoutMs: 100 })
+
+    rack.records().some((r: any) => r.cellId === 'D').should.be.true()
+    rack.records().some((r: any) => r.cellId === 'C').should.be.false()
+    crane.components.length.should.equal(0)
+  })
+})
+
+// ── Group 2: pick 자체가 실패한 케이스 ──────────────────────────────────────
+
+describe('R3 fix: pick 실패 시 carrier 그대로 source 에', async () => {
+  it('crane 이미 점유 → pick 실패 — carrier 가 source rack 에 그대로', async () => {
+    const rack = new FakeRack()
+    rack.state.data = [{ cellId: 'A' }]
+    const crane = new FakeCrane()
+    // crane 이 이미 다른 carrier 보유
+    const existing: any = {
+      placement: 'operation',
+      state: { type: 'parcel' },
+      parent: crane,
+      _transferSlotId: 'forks',
+      _realObject: { object3d: new THREE.Object3D() }
+    }
+    crane.components.push(existing)
+
+    const c = rack.obtainCarrier('A')!
+
+    let thrown: any
+    try {
+      await crane.pickAndPlace(c, rack.slotTargetAt('B'), { timeoutMs: 100 })
+    } catch (e) {
+      thrown = e
+    }
+
+    thrown.should.not.be.null()
+    // carrier 가 rack 의 child 그대로 (pick 자체가 실패라 mover 에 안 들어옴)
+    rack.components.includes(c).should.be.true()
+    crane.components.length.should.equal(1)   // 기존 점유 그대로
+  })
+})

package/test/test-phase-h-carrier-pickable.ts

@@ -93,13 +93,14 @@ describe('Phase H — Parcel pickupFrames', () => {
   })
 })
 
-describe('Phase H invariant — carrier 별 toolType 분리', () => {
-  it('Pallet 은 forklift-fork 만, Box 는 gripper 만 — 자동 호환성 검사 통과', () => {
+describe('Phase H invariant — carrier 별 primary tool', () => {
+  it('Pallet 의 primary tool 은 forklift-fork (gripper 없음), Box 는 gripper 포함', () => {
     const palletSrc = readSrc('../src/pallet.ts')
     const boxSrc = readSrc('../src/box.ts')
+    // Pallet 은 forklift-fork primary, gripper 직접 안 잡음 (Pallet 위 Box 를 잡음)
     palletSrc.should.match(/forklift-fork/)
     palletSrc.should.not.match(/toolType:\s*['"]gripper['"]/)
+    // Box 는 gripper 포함 (primary). 호환성 위해 agv-deck / forklift-fork 도 추가 가능.
     boxSrc.should.match(/gripper/)
-    boxSrc.should.not.match(/forklift-fork/)
   })
 })