# REQ-121: managed non-holding divergence 분류와 slot 존재 조회 계약

- Status: Approved
- Type: Data
- Priority: High
- Owner: trex-core-dev

## Intent
- broker-held symbol을 holding slot만으로 비교하면 동일 instance에 `inactive` 또는 `error` managed slot이 존재하는 경우도 true unmanaged position으로 잘못 분류된다.
- holding 수량 대조의 기존 의미론을 보존하면서, unmatched broker holding의 managed slot 존재 여부를 repository parity로 확인해 안전한 triage classification을 제공한다.

## Requirement
- 시스템은 `reconcile_core_holdings()`에서 broker-held symbol이 holding slot에 매칭되지 않을 때 동일 instance의 관리 slot 존재 여부를 조회해야 한다.
- slot이 전혀 없으면 기존 `unmanaged_position` 분류를 유지하고, slot은 존재하지만 non-holding 상태이면 `managed_non_holding_divergence`로 별도 분류해야 한다.
- 이 분류는 slot 상태 전이, warning 자동 해제, 자동 매매, 자동 청산 또는 unmanaged holding의 자동 slot 생성을 유발하지 않아야 하며, 상태 수렴은 기존 승인 gate의 검증된 `sync` 경로에만 맡겨야 한다.
- SlotRepository Protocol과 PostgreSQL/InMemory 구현은 instance-scoped managed-slot existence query에 대해 동등한 결과를 제공해야 한다.

## Acceptance Criteria
1. Given broker-held symbol에 대해 대상 instance에 어떤 slot도 없음, When `reconcile_core_holdings()`를 실행하면, Then `unmanaged_position` decision code와 기존 safe warning semantics가 유지된다.
2. Given broker-held symbol에 대해 같은 instance의 slot이 `inactive` 또는 `error`이고 holding slot은 없음, When `reconcile_core_holdings()`를 실행하면, Then `managed_non_holding_divergence` decision code와 `slot_id`, `portfolio_id`, `symbol`, `status`, `instance_key`의 구조화·비밀 없는 triage context가 남는다.
3. Given matching holding slot 또는 holding qty mismatch, When `reconcile_core_holdings()`를 실행하면, Then 각각 기존 match 및 mismatch path가 유지되고 non-holding divergence로 재분류되지 않는다.
4. Given AC-1~3 fixture, When reconciliation 후 slot 및 warning persistence를 검사하면, Then managed non-holding 분류만으로 slot state write, warning 자동 해제, 자동 매매, 자동 청산 또는 unmanaged slot 생성이 발생하지 않는다.
5. Given PostgreSQL 및 InMemory SlotRepository, When 같은 instance/symbol/portfolio fixture로 managed-slot existence query를 실행하면, Then 두 구현이 같은 존재 여부와 instance isolation 결과를 반환한다.
6. Given 다른 instance에만 같은 symbol 또는 portfolio_id slot이 존재함, When reconciliation을 실행하면, Then 그것은 대상 instance의 managed slot으로 취급되지 않는다.

## Impacted Area
- Docs: `docs/runtime-flows.md`, `docs/interface-contract.md`, `docs/operations.md`, `docs/srs/Integration/req-103_blocking-reconcile-b-c-cases.md`, `docs/srs/Interface/req-105_sync-cli-command.md`
- Modules: `trex_core/application/reconciliation.py`, `trex_core/domain/slot/repository.py`, `trex_core/adapters/persistence/postgresql.py`, `trex_core/domain/slot/in_memory_repository.py`
- Tests: reconciliation 4-case regression matrix; PostgreSQL/InMemory repository parity; instance isolation; no-auto-write/no-auto-remediation assertions

## Notes
- Source Discovery: `docs/discovery/dcy-037_20260714_operator-broker-truth-and-managed-slot-divergence-hotfix.md` (FR-4~5, NFR-2~4; GitHub #41).
- Existing `list_holding_slots(instance_key)` is holding-only evidence; this REQ adds the separate managed-slot existence decision needed only after an unmatched broker holding.
- This is additive classification. `sync --live` target selection and execution remain release-gated and out of scope.

## Change Log

### CHG-20260714-01
- Date: 2026-07-14
- Author: delivery-runner

#### Change Summary
- dcy-037 #41의 managed non-holding divergence와 repository query parity를 Proposed REQ로 초안화했다.

#### Intent
- 진짜 unmanaged broker holding과 이미 관리되는 non-holding slot divergence를 혼동하지 않도록 한다.

#### Acceptance Criteria Delta
- Added:
  - 4-case reconciliation matrix, repository parity/instance isolation, additive no-auto-remediation constraints.
- Updated:
  - 없음.
- Removed:
  - 없음.

#### Impacted Area Delta
- Docs:
  - reconcile decision 및 operator triage baseline.
- Modules:
  - reconciliation 및 slot repository protocol/implementations.
- Tests:
  - application classification 및 DB/in-memory parity regression.

#### Delivery Trace Delta
- Batches:
  - none (draft only; dcy-037 emergency scope의 향후 입력).
- Releases:
  - none (production read/write 또는 live sync 실행 없음).

#### Revalidation Impact
- Reverification Needed: yes
- Existing Implementation Invalidated: no
- Status Recommendation: keep-current
- Follow-up Action: confirm-req 전 decision-code naming과 existing warning/alert inventory compatibility를 검토한다.

#### Validation Plan
- isolated four-case fixture와 PostgreSQL/InMemory parity suite에서 classification, structured context, instance scope 및 no-write invariant를 검증한다.

### CHG-20260714-02
- Date: 2026-07-14
- Author: Justin (TREX lead)

#### Change Summary
- Proposed에서 Approved로 승인했다.

#### Intent
- dcy-037 #41의 additive classification을 기존 holding mismatch와 unmanaged semantics를 보존하는 delivery input으로 확정한다.

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

#### Impacted Area Delta
- Docs:
  - 없음.
- Modules:
  - 없음.
- Tests:
  - 없음.

#### Delivery Trace Delta
- Batches:
  - dcy-037의 #39/#40/#41 단일 emergency batch (아직 미생성).
- Releases:
  - none; `sync --live`는 별도 release approval gate 유지.

#### Revalidation Impact
- Reverification Needed: yes
- Existing Implementation Invalidated: no
- Status Recommendation: keep-current
- Follow-up Action: suggest-batch-reqs에서 REQ-119/120과 함께 emergency batch로 편성한다.

#### Validation Plan
- batch verification과 독립 QC에서 4-case matrix, repository parity, instance isolation 및 no-auto-remediation AC를 재검증한다.