trex-core/docs/srs/Data/req-121_managed-non-holding-divergence-classification-query.md

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

• Status: Implemented
• 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-45, NFR-24; 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를 재검증한다.

CHG-20260715-03

• Date: 2026-07-15
• Author: TREX lead

Change Summary

• Approved → Implemented (confirm-req-implemented).

Delivery Trace

• BAT-057 verification confirmed; PR #42 merged to main as 94e148940adb008db0bbd215052a1e984f7c566b.
• Independent QC: PASS-WITH-NOTES, acceptance blocker 0. Fake-driver PostgreSQL adapter/InMemory parity is accepted AC evidence; real PostgreSQL engine integration remains an environmental coverage note.