trex-core/docs/srs/Interface/req-059_active-capacity-admission.md

req-059: 활성 capacity 제어 + 신호 기반 admission (FCFS·M캡·무치환·over-cap)

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

Intent

• 익명 슬롯 배정 대신 "동시 활성(holding) 최대 M개" 정책으로 capacity 를 제어하고, 매수/매도 신호를 해당 자산 슬롯의 활성화/비활성화로 처리한다. (dcy-020 FR-2/FR-3/OQ-1/OQ-8)

Requirement

• 매수 신호는 해당 자산 슬롯을 활성화(inactive→pending_buy)한다. 활성(holding+pending_buy) 수 < M 이면 즉시 활성화, == M 이면 거부(capacity_full) 한다. 코어는 자리를 만들려고 기존 holding 을 자율 청산(치환)하지 않는다(FCFS·무치환). 동시 후보 tie-break 은 updated_at asc → portfolio_id(alpha 비사용). M 을 현재 보유 수보다 작게 바꿔 over-cap 이 되면 신규 활성화만 차단하고 기존 보유는 자연 종료까지 유지한다(강제 청산 없음). 마지막 슬롯 경합은 인스턴스 스코프 advisory lock + 재시도로 직렬화한다.

Acceptance Criteria

1. Given 활성 수 < M, When 자산 매수 신호, Then 그 자산 슬롯이 pending_buy 로 활성화된다.
2. Given 활성 수 == M, When 새 자산 매수 신호, Then capacity_full 로 거부되고 기존 holding 은 청산되지 않는다.
3. Given 이미 활성(pending_buy/holding/pending_sell)인 자산, When 또 매수 신호, Then 멱등 거부(already_active)된다.
4. Given M 을 현재 보유 수보다 작게 변경(over-cap), When 신규 매수 신호, Then 활성 수가 M 이하로 내려갈 때까지 신규만 거부되고 기존 보유는 유지된다.
5. Given 동시 매수 신호 경합, When 병렬 처리, Then 인스턴스 스코프 락으로 직렬화되어 M 초과 활성화가 발생하지 않는다.

Impacted Area

• Docs: docs/runtime-flows.md(admission→활성화 흐름)
• Modules: trex_core/application/intents.py, trex_core/application/portfolio.py(capacity 개념)
• Tests: tests/application/test_intent_concurrency.py, tests/application/test_admission.py

Notes

• M 값 출처는 REQ-060(per-instance TOML). 기존 REQ-007(admission) 재정의 change-req 동반(find_allocatable_slot/idle 배정 폐기).
• 출처: dcy-020 FR-2, FR-3, OQ-1, OQ-8.

Change Log

CHG-20260610-01

• Date: 2026-06-10
• Author: Justin Ko

Change Summary

• dcy-020 FR-2/FR-3/OQ-1/OQ-8 로부터 최초 생성(Proposed). FCFS + M 캡 + capacity_full 거부 + 무치환 + over-cap(신규만 차단) + already_active.

Intent

• 신호 기반 활성화/비활성화와 동시 활성 M 제어를 backlog 로 정규화.

Acceptance Criteria Delta

• Added: 활성화/거부/already_active/over-cap/경합 직렬화 5개 기준
• Updated: 없음
• Removed: 없음

Impacted Area Delta

• Docs: docs/runtime-flows.md
• Modules: application/intents.py, portfolio.py
• Tests: test_intent_concurrency.py, admission 테스트

Delivery Trace Delta

• Batches: none
• Releases: none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: confirm-req. REQ-007 재정의 change-req·REQ-060(M) 의존.

Validation Plan

• FCFS/거부/over-cap/경합 단위·통합 테스트 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-028(+BAT-030 단일 경로·capacity_full e2e) — 모든 AC 가 release-candidate 배치 verification 의 evidence 와 연결됨(단위 367/PG 29/MQ 21 passed + run-the-app 자산 중심 e2e). Blocking Issues 없음.