# req-057: 자산 영구 슬롯 상태머신 재정의 + 인스턴스 스코프 advisory lock

- Status: Implemented
- Type: Interface
- Priority: High
- Owner: project maintainers

## Intent
- 영구 자산 슬롯에 맞춰 슬롯 상태머신을 재정의하고, holding 을 코어 로컬 정본으로 두며, 공유 DB 다중 인스턴스에서 단일 writer 불변식을 인스턴스 단위로 보존한다. (dcy-020 FR-6/FR-3/NFR-1)

## Requirement
- 상태 집합을 `inactive → pending_buy → holding → pending_sell → inactive` (+ 모든 비-error → `error`, `error → {inactive, holding}` 운영자 resolve)로 재정의한다. 기존 `idle`·`closed` 는 영구 슬롯에서 단일 `inactive` 로 합치고 `closed→idle` 복구 전이를 제거한다. `holding`(포지션 열림)은 코어 슬롯의 로컬 정본으로 체결 시 동기 set, 매도 체결 시 동기 clear 한다(portfolio-hub `asset_quantity` 로 판단하지 않음). advisory lock 을 **인스턴스 스코프**(`pg_advisory_xact_lock(SLOT_LOCK_ID, hash(instance_key))`)로 두어 인스턴스 간 교차 직렬화를 제거한다.

## Acceptance Criteria
1. Given 상태머신, When 허용 전이 집합을 확인, Then `{inactive→pending_buy, pending_buy→holding, pending_buy→inactive, holding→pending_sell, pending_sell→inactive, pending_sell→holding, *→error, error→inactive, error→holding}` 와 정확히 일치한다.
2. Given 영구 슬롯, When 매도 체결로 종료, Then 슬롯은 `inactive` 로 돌아가고(별도 `closed`·`closed→idle` 없음) holding 로컬 플래그가 clear 된다.
3. Given 서로 다른 instance_key 의 두 슬롯, When 동시에 전이, Then 인스턴스별 락으로 서로를 차단하지 않는다(교차 경합 없음).
4. Given 같은 슬롯에 대한 동시 전이, When 병렬 처리, Then 인스턴스 스코프 락으로 직렬화되어 단일 writer 불변식이 유지된다.

## Impacted Area
- Docs: docs/runtime-flows.md(전이 흐름), docs/data-model.md(상태)
- Modules: trex_core/domain/slot/state.py, trex_core/domain/slot/service.py, trex_core/domain/slot/models.py
- Tests: tests/domain/slot/test_state.py, tests/domain/slot/test_service.py

## Notes
- 기존 REQ-002(상태머신·서비스) 재정의 change-req 동반. dcy-001 의 6상태/closed→idle 모델 폐기.
- holding 로컬 정본 근거(offline 안전·universe 누락 생존·hub 지연·capacity 원자성)는 dcy-020 FR-3.
- 출처: dcy-020 FR-6, FR-3, NFR-1, OQ-7.

## Change Log

### CHG-20260610-01
- Date: 2026-06-10
- Author: Justin Ko

#### Change Summary
- dcy-020 FR-6/FR-3/NFR-1 로부터 최초 생성(Proposed). 상태머신 재정의(idle/closed→inactive, closed→idle 제거) + holding 로컬 정본 + 인스턴스 스코프 advisory lock.

#### Intent
- 영구 자산 슬롯 상태머신·holding 로컬·인스턴스 단위 단일 writer 를 backlog 로 정규화.

#### Acceptance Criteria Delta
- Added:
  - 전이 집합/inactive 종료/인스턴스별 락 비교차/동일 슬롯 직렬화 4개 기준
- Updated: 없음
- Removed: 없음

#### Impacted Area Delta
- Docs: docs/runtime-flows.md, docs/data-model.md
- Modules: domain/slot/state.py, service.py, models.py
- Tests: test_state.py, test_service.py

#### Delivery Trace Delta
- Batches: none
- Releases: none

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no (신규 정의; REQ-002 재정의 change-req 로 기존 폐기)
- Status Recommendation: keep-current
- Follow-up Action: confirm-req. REQ-002 change-req 동반.

#### Validation Plan
- 전이 허용/거부 집합 + 인스턴스 락 단위테스트 green.

### CHG-20260610-02
- Date: 2026-06-10
- Author: Justin Ko

#### Change Summary
- Status Proposed → Approved (confirm-req). 필수 필드·구체 AC 충족, source dcy-020(confirmed, handoff 승인)과 모순 없음.

#### Intent
- delivery input 으로 승격.

#### Acceptance Criteria Delta
- Added: 없음 / Updated: 없음 / Removed: 없음

#### Impacted Area Delta
- Docs: docs/srs/index.md (Register Approved) / Modules: 없음 / Tests: 없음

#### Delivery Trace Delta
- Batches: none / Releases: none

#### Revalidation Impact
- Reverification Needed: no / Existing Implementation Invalidated: no / Status Recommendation: keep-current / Follow-up Action: suggest-batch-reqs / draft-batch.

#### Validation Plan
- 승인 후 batch planning 에서 본 REQ AC 를 검증 기준으로 사용.

### CHG-20260610-IMPL
- Date: 2026-06-10
- Author: Justin Ko
- Type: status
- Summary: Approved → Implemented (confirm-req-implemented). 근거: BAT-027(토대)+BAT-030(literal inactive·별칭 제거) — 모든 AC 가 release-candidate 배치 verification 의 evidence 와 연결됨(단위 367/PG 29/MQ 21 passed + run-the-app 자산 중심 e2e). Blocking Issues 없음.