@operato/scene-storage 10.0.0-beta.41 → 10.0.0-beta.43

package/test/test-rack-concurrent.ts

@@ -0,0 +1,254 @@
+/*
+ * Plan A 의 *동시성 / 멱등성* 검증.
+ *
+ * Stuck pickAndPlace, ghost mover 가 시스템 락 만드는 회귀의 근본 원인 = *불변식이
+ * 동시 호출 / 재호출 시 깨짐*. 여기선 그 불변식들을 격리 검증.
+ *
+ * 검증 케이스:
+ *   - 같은 cellId 로 obtainCarrier 를 연속 호출 — 두 번째는 *기존 carrier 그대로* 반환
+ *     (새 인스턴스 안 만듦)
+ *   - 같은 cellId 로 receiveAt 를 동시에 시도 — 첫 성공, 두 번째 reject
+ *   - obtainCarrier 후 receiveAt 까지의 시퀀스가 *원자성* — 다른 호출이 끼어들어도
+ *     state.data 의 record + carrier-children 의 *합* 이 보존
+ */
+
+import 'should'
+import * as THREE from 'three'
+
+// FakeRack — SlottedHolder 의 *불변식 검증* 용
+class FakeRack {
+  state: any = { data: [] }
+  components: any[] = []
+  rootObject3d = new THREE.Group()
+  _slotAnchors = new Map<string, THREE.Object3D>()
+
+  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 => r.cellId === cellId)
+  }
+
+  canReceiveAt(cellId: string): boolean {
+    return !this.hasCarrierAt(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                          // idempotent — 이미 있으면 그대로
+    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,
+      dispose() { this._disposed = true }
+    }
+    this.addComponent(c)
+    this.state.data = this.records().filter((_, j) => j !== idx)
+    return c
+  }
+
+  async receiveAt(cellId: string, carrier: any): Promise<{ ok: boolean; reason?: string }> {
+    if (!this.canReceiveAt(cellId)) return { ok: false, reason: 'slot-occupied' }
+    const p = carrier.parent
+    if (p?.removeComponent) p.removeComponent(carrier)
+    carrier.dispose?.()
+    const rec = { cellId, type: carrier.state.type ?? 'parcel', sku: carrier.state.sku }
+    this.state.data = [...this.records(), rec]
+    return { ok: true }
+  }
+}
+
+// ── Group 1: obtainCarrier 의 멱등성 ────────────────────────────────────────
+
+describe('Concurrent: obtainCarrier 멱등성', () => {
+  it('같은 cellId 로 두 번 호출 → 같은 인스턴스 반환', () => {
+    const rack = new FakeRack()
+    rack.state.data = [{ cellId: 'A', sku: 'X' }]
+
+    const c1 = rack.obtainCarrier('A')
+    const c2 = rack.obtainCarrier('A')
+
+    c1.should.equal(c2)
+    rack.records().length.should.equal(0)   // record 는 한 번만 빠짐
+    rack.components.length.should.equal(1)  // carrier 도 한 개
+  })
+
+  it('첫 obtain → pick 으로 옮긴 후 → 두 번째 obtain → null (record 도 carrier 도 없음)', () => {
+    const rack = new FakeRack()
+    rack.state.data = [{ cellId: 'A' }]
+    const elsewhere: any = { removeComponent(c: any) { c.parent = null } }
+
+    const c1 = rack.obtainCarrier('A')!
+    // 외부로 픽업 (simulated mover.pick)
+    rack.removeComponent(c1)
+    c1.parent = elsewhere
+
+    const c2 = rack.obtainCarrier('A')
+    ;(c2 === null).should.be.true()
+  })
+
+  it('record 와 carrier-child 가 다른 cellId 면 각각 독립적으로 obtain', () => {
+    const rack = new FakeRack()
+    rack.state.data = [{ cellId: 'A', sku: 'a' }, { cellId: 'B', sku: 'b' }]
+
+    const cA = rack.obtainCarrier('A')!
+    const cB = rack.obtainCarrier('B')!
+
+    ;(cA !== cB).should.be.true()
+    cA.state.sku.should.equal('a')
+    cB.state.sku.should.equal('b')
+    rack.records().length.should.equal(0)
+  })
+})
+
+// ── Group 2: receiveAt 의 원자성 ────────────────────────────────────────────
+
+describe('Concurrent: receiveAt 원자성', () => {
+  it('같은 cellId 로 동시 receiveAt — 첫 성공, 두 번째 reject', async () => {
+    const rack = new FakeRack()
+    const mover: any = { removeComponent(c: any) { c.parent = null } }
+
+    const c1 = { placement: 'operation', state: { type: 'parcel', sku: 'first' }, parent: mover, dispose() {} } as any
+    const c2 = { placement: 'operation', state: { type: 'parcel', sku: 'second' }, parent: mover, dispose() {} } as any
+
+    const [r1, r2] = await Promise.all([
+      rack.receiveAt('A', c1),
+      rack.receiveAt('A', c2)
+    ])
+
+    // 둘 중 하나만 ok
+    const okCount = [r1, r2].filter(r => r.ok).length
+    okCount.should.equal(1)
+    rack.records().length.should.equal(1)
+    rack.records()[0].cellId.should.equal('A')
+  })
+
+  it('다른 cellId 로 동시 receiveAt — 둘 다 성공', async () => {
+    const rack = new FakeRack()
+    const mover: any = { removeComponent(c: any) { c.parent = null } }
+
+    const cA = { placement: 'operation', state: { type: 'parcel' }, parent: mover, dispose() {} } as any
+    const cB = { placement: 'operation', state: { type: 'parcel' }, parent: mover, dispose() {} } as any
+
+    const [rA, rB] = await Promise.all([
+      rack.receiveAt('A', cA),
+      rack.receiveAt('B', cB)
+    ])
+
+    rA.ok.should.be.true()
+    rB.ok.should.be.true()
+    rack.records().length.should.equal(2)
+  })
+})
+
+// ── Group 3: round-trip 의 invariant ────────────────────────────────────────
+
+describe('Concurrent: 전체 round-trip 후 state 일관성', () => {
+  it('A → mover → B 전체 후 — record 가 정확히 1개 (B에)', async () => {
+    const rack = new FakeRack()
+    rack.state.data = [{ cellId: 'A', sku: 'X' }]
+    const mover: any = {
+      add(c: any) { c.parent = mover },
+      removeComponent(c: any) { c.parent = null }
+    }
+
+    // 1. obtain A
+    const c = rack.obtainCarrier('A')!
+    rack.records().length.should.equal(0)
+
+    // 2. mover picks
+    rack.removeComponent(c)
+    mover.add(c)
+    rack.records().length.should.equal(0)
+    rack.components.length.should.equal(0)
+
+    // 3. mover places at B
+    await rack.receiveAt('B', c)
+    rack.records().length.should.equal(1)
+    rack.records()[0].cellId.should.equal('B')
+    rack.records()[0].sku.should.equal('X')
+    rack.components.length.should.equal(0)
+  })
+
+  it('A → mover → A (원래 자리로 복귀) — record A 가 다시 들어옴', async () => {
+    const rack = new FakeRack()
+    rack.state.data = [{ cellId: 'A', sku: 'X' }]
+    const mover: any = { removeComponent(c: any) { c.parent = null } }
+
+    const c = rack.obtainCarrier('A')!
+    rack.removeComponent(c)
+    c.parent = mover
+    await rack.receiveAt('A', c)
+
+    rack.records().length.should.equal(1)
+    rack.records()[0].cellId.should.equal('A')
+  })
+
+  it('A → mover → 외부 (다른 holder) — rack.records 비어있고 외부에 carrier 1개', () => {
+    const rack = new FakeRack()
+    rack.state.data = [{ cellId: 'A' }]
+    const externalHolder: any = {
+      components: [] as any[],
+      addComponent(c: any) { c.parent = this; this.components.push(c) }
+    }
+
+    const c = rack.obtainCarrier('A')!
+    rack.removeComponent(c)
+    externalHolder.addComponent(c)
+
+    rack.records().length.should.equal(0)
+    rack.components.length.should.equal(0)
+    externalHolder.components.length.should.equal(1)
+    c.parent.should.equal(externalHolder)
+  })
+})
+
+// ── Group 4: 동시 obtain 의 race 방지 (sync 가정) ────────────────────────────
+
+describe('Concurrent: 동시 호출의 race condition 방지', () => {
+  it('rapid 연속 obtainCarrier 가 record 를 *2번 소비하지 않음*', () => {
+    const rack = new FakeRack()
+    rack.state.data = [{ cellId: 'A' }]
+
+    // 동기 연속 (event loop 진입 안 함)
+    const c1 = rack.obtainCarrier('A')
+    const c2 = rack.obtainCarrier('A')
+    const c3 = rack.obtainCarrier('A')
+
+    c1!.should.equal(c2)
+    c2!.should.equal(c3)
+    rack.records().length.should.equal(0)
+    rack.components.length.should.equal(1)
+  })
+
+  it('obtain → carrier 가 다른 곳으로 떠난 후 → 또 obtain → null', () => {
+    const rack = new FakeRack()
+    rack.state.data = [{ cellId: 'A' }]
+    const mover: any = { removeComponent(c: any) { c.parent = null } }
+
+    const c1 = rack.obtainCarrier('A')!
+    rack.removeComponent(c1)
+    c1.parent = mover
+
+    // 이제 rack 에는 record 도 carrier-child 도 없음
+    const c2 = rack.obtainCarrier('A')
+    ;(c2 === null).should.be.true()
+  })
+})

package/test/test-rack-edge-cases.ts

@@ -0,0 +1,323 @@
+/*
+ * Edge case + 결함 식별 — Plan A 의 가정이 깨지는 시나리오를 *적극 탐사*.
+ *
+ * 목표: 정상 path 만 검증하는 게 아니라, application 이 자주 만드는 *비정상 입력*
+ * 과 *race* 상황에서 어디가 깨지는지 드러내기.
+ */
+
+import 'should'
+import * as THREE from 'three'
+
+class FakeRack {
+  state: any = { data: [] }
+  components: any[] = []
+  rootObject3d = new THREE.Group()
+  _slotAnchors = new Map<string, THREE.Object3D>()
+
+  records(): any[] { return this.state.data ?? [] }
+
+  ensureSlotAnchor(cellId: string): THREE.Object3D {
+    let a = this._slotAnchors.get(cellId)
+    if (!a) {
+      a = new THREE.Object3D()
+      a.name = `slot:${cellId}`
+      this.rootObject3d.add(a)
+      this._slotAnchors.set(cellId, a)
+    }
+    return a
+  }
+
+  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 => r.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
+  }
+
+  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
+  }
+
+  attachPointFor(carrier: any) {
+    const cellId = carrier?.state?.cellId
+    if (cellId) return { attach: this.ensureSlotAnchor(cellId), localPosition: { x: 0, y: 0, z: 0 } }
+    return { attach: this.rootObject3d, localPosition: { x: 0, y: 0, z: 0 } }
+  }
+
+  obtainCarrier(cellId: string): any {
+    const existing = this.carrierAt(cellId)
+    if (existing) return existing
+    const records = this.records()
+    const idx = records.findIndex(r => r?.cellId === cellId)
+    if (idx === -1) return null
+    const record = 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)
+    const pt = this.attachPointFor(c)
+    pt.attach.attach(c._realObject.object3d)
+    c._realObject.object3d.position.set(pt.localPosition.x, pt.localPosition.y, pt.localPosition.z)
+    // *모든* 동일 cellId record 정리 (중복 방어)
+    this.state.data = 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?.()
+    // 중복 방어: 동일 cellId 의 기존 record 가 있으면 (외부 결함) 제거 후 단일 추가
+    const remaining = this.records().filter(r => r?.cellId !== cellId)
+    this.state.data = [...remaining, { cellId, type: carrier.state.type ?? 'parcel', sku: carrier.state.sku }]
+  }
+}
+
+// ── E1: state.data 가 corrupted 한 케이스 ─────────────────────────────────────
+
+describe('Edge: state.data 비정상 입력', () => {
+  it('R5 FIXED — 중복 cellId record 가 *한 번에 모두 정리됨* (ghost 차단)', () => {
+    const rack = new FakeRack()
+    rack.state.data = [
+      { cellId: 'A', sku: 'first' },
+      { cellId: 'A', sku: 'duplicate' }   // 중복
+    ]
+
+    const c1 = rack.obtainCarrier('A')!
+    c1.state.sku.should.equal('first')          // 첫 record 가 materialize
+    rack.records().length.should.equal(0)        // 중복 record 도 한 번에 제거 (Fix 적용)
+
+    // idempotent — 두 번째 호출은 기존 c1 반환 (다른 인스턴스 안 만듦)
+    const c2 = rack.obtainCarrier('A')!
+    c2.should.equal(c1)
+    rack.components.length.should.equal(1)       // carrier 하나만 존재
+  })
+
+  it('R6 — state.data 가 undefined 일 때 obtainCarrier 안전한가?', () => {
+    const rack = new FakeRack()
+    rack.state.data = undefined as any
+    const c = rack.obtainCarrier('A')
+    ;(c === null).should.be.true()
+  })
+
+  it('R7 — state.data 에 cellId 가 null/undefined 인 record', () => {
+    const rack = new FakeRack()
+    rack.state.data = [{ sku: 'no-cell' }, { cellId: null, sku: 'null-cell' }, { cellId: 'A', sku: 'ok' }]
+    // 첫 두 record 는 cellId 가 없음 → InstancedMesh 도 못 그리지만 obtainCarrier 영향?
+    const c = rack.obtainCarrier('A')!
+    c.state.sku.should.equal('ok')
+    // 비정상 record 는 그대로 남음 (silent ignore)
+    rack.records().length.should.equal(2)
+    console.log('  → R7: cellId 없는 record 가 *그대로 잔존*. 청소되지 않음.')
+  })
+})
+
+// ── E2: 이미 carrier-child 있는 cellId 로 receiveAt ────────────────────────
+
+describe('Edge: receiveAt 충돌', () => {
+  it('R8 — carrier-child 있는 cellId 로 receiveAt → slot-occupied 거부', async () => {
+    const rack = new FakeRack()
+    rack.state.data = [{ cellId: 'A' }]
+    const c1 = rack.obtainCarrier('A')!
+    rack.removeComponent(c1)
+    const mover: any = { removeComponent: (c: any) => { c.parent = null } }
+    c1.parent = mover
+
+    // record 는 없지만 carrier child 가 있다고 가정 (다른 carrier)
+    const phantom: any = {
+      placement: 'operation',
+      state: { cellId: 'A' },
+      parent: rack
+    }
+    rack.components.push(phantom)
+
+    let thrown: any
+    try { await rack.receiveAt('A', c1) } catch (e) { thrown = e }
+    thrown.should.not.be.null()
+    thrown.reason.should.equal('slot-occupied')
+  })
+
+  it('R9 — receiveAt 가 carrier 의 *현재 parent 가 잘못된 케이스* 처리', async () => {
+    const rack = new FakeRack()
+    // carrier 가 어떤 parent 에도 없는 *orphan* 인 경우
+    const orphan: any = {
+      placement: 'operation',
+      state: { type: 'parcel' },
+      parent: null,
+      _realObject: { object3d: new THREE.Group() },
+      dispose() { this._disposed = true; this._realObject.object3d.clear() }
+    }
+    // 여전히 receiveAt 호출되면?
+    await rack.receiveAt('A', orphan)
+    rack.records().length.should.equal(1)
+    orphan._disposed.should.be.true()
+  })
+
+  it('R10 — receiveAt 가 carrier._realObject 없는 케이스 처리', async () => {
+    const rack = new FakeRack()
+    const broken: any = {
+      placement: 'operation',
+      state: { type: 'parcel' },
+      parent: null,
+      _realObject: null,                  // 비정상
+      dispose() { this._disposed = true }
+    }
+    await rack.receiveAt('A', broken)    // throw 안 하고 graceful
+    broken._disposed.should.be.true()
+    rack.records().length.should.equal(1)
+  })
+})
+
+// ── E3: applyHolderAttachPoint 의 부정확한 시점 ───────────────────────────
+
+describe('Edge: applyHolderAttachPoint 타이밍', () => {
+  it('R11 — _realObject 가 *아직 build 안 된 시점* 에 applyHolderAttachPoint 호출', () => {
+    const rack = new FakeRack()
+    // 일반적으로 obtainCarrier 가 _realObject 를 미리 만들지만, 외부에서 직접 add 시
+    // _realObject 가 lazy 라 빌드 안 된 채 호출될 수 있음
+    const carrier: any = {
+      placement: 'operation',
+      state: { cellId: 'A' },
+      parent: null,
+      _realObject: null,                  // 아직 빌드 안 됨
+      dispose() {}
+    }
+    rack.addComponent(carrier)
+    // applyHolderAttachPoint 가 _realObject null 이라 silent skip 해야 함
+    const pt = rack.attachPointFor(carrier)
+    pt.attach.name.should.equal('slot:A')
+    // 호출 자체는 graceful — application 이 _realObject 빌드 후 다시 호출 책임
+  })
+
+  it('R12 — cellId 가 없는 carrier 가 add 됐을 때 attachPointFor 가 rack root 로 fallback', () => {
+    const rack = new FakeRack()
+    const noIdCarrier: any = {
+      placement: 'operation',
+      state: { type: 'parcel' },   // cellId 없음
+      parent: rack
+    }
+    const pt = rack.attachPointFor(noIdCarrier)
+    pt.attach.should.equal(rack.rootObject3d)
+    // 결함 R12 — *위치 정보 없는* carrier 가 rack 의 *root* 에 attach 됨 → 시각적으로 rack
+    // 의 origin (보통 한 모서리 또는 중심) 에 ghost 처럼 떠있게 됨.
+    console.log('  → R12: cellId 없는 carrier 는 rack root 에 attach → 시각 결함 가능.')
+  })
+})
+
+// ── E4: dispose 의 부분적 실패 ─────────────────────────────────────────────
+
+describe('Edge: dispose 부분적 실패', () => {
+  it('R13 — dispose 중 예외 발생 시 state.data 는 *덮어쓰기 되지 않아야*', async () => {
+    const rack = new FakeRack()
+    rack.state.data = [{ cellId: 'A' }]
+    const c = rack.obtainCarrier('A')!
+
+    // dispose 가 throw 하는 carrier 시뮬
+    c.dispose = function() {
+      this._disposed = true
+      throw new Error('dispose failed')
+    }
+
+    let thrown: any
+    try { await rack.receiveAt('B', c) } catch (e) { thrown = e }
+
+    // 결함 R13 발견 — 현재 코드는 dispose 의 throw 를 catch 안 함 → 전체 receiveAt 가 throw
+    // → state.data push 가 실행 안 됨 → carrier 가 *부분 정리된 상태* 로 남음
+    if (thrown) {
+      console.log('  → R13: dispose throw → receiveAt 가 *불완전* 종료. state.data 에 push 안 됨.')
+      console.log('  → carrier.parent 가 null (removeComponent 는 이미 됨) 이지만 _disposed=true 인 zombie 상태.')
+      ;(c.parent === null).should.be.true()
+      c._disposed.should.be.true()
+      rack.records().length.should.equal(0)   // ← 결함: record 누락
+    }
+  })
+})
+
+// ── E5: SlotTarget 의 carrier-mismatch ────────────────────────────────────
+
+describe('Edge: SlotTarget 의 carrier 일관성', () => {
+  it('R14 — SlotTarget.receive 에 *예상치 못한 carrier* 가 들어와도 거부?', async () => {
+    const rack = new FakeRack()
+    rack.state.data = [{ cellId: 'A' }]
+    const externalCarrier: any = {
+      placement: 'operation',
+      state: { id: 'external', type: 'foreign-type' },
+      parent: null,
+      dispose() { this._disposed = true }
+    }
+    // dest A 는 이미 record 있어 occupied. receive 호출 시 reject 되어야 함
+    let thrown: any
+    try { await rack.receiveAt('A', externalCarrier) } catch (e) { thrown = e }
+    thrown.should.not.be.null()
+    thrown.reason.should.equal('slot-occupied')
+    // 정상 거부 — externalCarrier 는 dispose 안 됐어야 함 (rollback)
+    ;(externalCarrier._disposed !== true).should.be.true()
+  })
+
+  it('R15 — receiveAt 가 *carrier 의 type 검증* 안 함 — 의도된 limitation?', async () => {
+    const rack = new FakeRack()
+    const weird: any = {
+      placement: 'operation',
+      state: { type: 'storage-cell' },   // 셀 타입의 carrier?? 이상한 입력
+      parent: null,
+      dispose() { this._disposed = true }
+    }
+    await rack.receiveAt('A', weird)
+    rack.records().length.should.equal(1)
+    rack.records()[0].type.should.equal('storage-cell')
+    console.log('  → R15: receiveAt 가 type 검증 안 함 — *어떤 carrier 도 받음*. 의도된 design.')
+  })
+})
+
+// ── E6: rapid 연속 obtainCarrier + receiveAt 의 race ──────────────────────
+
+describe('Edge: 빠른 연속 호출의 race', () => {
+  it('R16 — obtainCarrier 직후 receiveAt 같은 cellId 로 다시 — 정상 동작?', async () => {
+    const rack = new FakeRack()
+    rack.state.data = [{ cellId: 'A' }]
+    const c = rack.obtainCarrier('A')!
+    // 같은 cellId 로 다시 receiveAt — 자기 자신을 자기 자리로 환원 (의미: undo obtain)
+    await rack.receiveAt('A', c)
+    rack.records().length.should.equal(1)
+    rack.records()[0].cellId.should.equal('A')
+    rack.components.length.should.equal(0)
+  })
+
+  it('R17 — obtain → receive → obtain → receive 사이클 — state 누적 없음', async () => {
+    const rack = new FakeRack()
+    rack.state.data = [{ cellId: 'A', sku: 'X' }]
+
+    for (let i = 0; i < 50; i++) {
+      const c = rack.obtainCarrier('A')!
+      await rack.receiveAt('A', c)
+    }
+    rack.records().length.should.equal(1)
+    rack.records()[0].cellId.should.equal('A')
+    rack.records()[0].sku.should.equal('X')
+    rack.components.length.should.equal(0)
+    rack._slotAnchors.size.should.equal(1)   // anchor 하나만 (singleton 보장)
+  })
+})