diff --git a/docs/releases/index.md b/docs/releases/index.md index 7fe3c94..c336011 100644 --- a/docs/releases/index.md +++ b/docs/releases/index.md @@ -18,3 +18,4 @@ | REL-008 | app-service | feedback-captured | BAT-042, BAT-043, BAT-044, BAT-045, BAT-046 | dcy-028/issue #26 (slot strategy-state) + issue #27 (sell retryable) + dcy-030/issue #28 (호가단위 스냅, P0 체결 복구) + dcy-029/issue #29 (운영 관측성 — 구조화 로깅·주문결과·거부ERROR·reason+actor·PnL CLI·런북) — 통합 릴리즈 | [rel-008](rel-008_20260616_tick-snap-and-observability.md) | | REL-009 | app-service | feedback-captured | BAT-047, BAT-048, BAT-049 | dcy-031/OPS-005 (이벤트 발행 신뢰성 — idle keepalive·재시도·DLQ 경보) + dcy-032 (체결가 0/None 백필 가드·WARN 로깅) + dcy-033 (알람 emitter + trex.alerts exchange 1단계) + dcy-017 후속(무데이터/죽은 종목 위생 런북 docs-only) — M2 통합 릴리즈. 환류: OPS-005 해소 확인, slot_filled NO_ROUTE/DLQ 신규 발견(M3 Discovery 입력) | [rel-009](rel-009_20260625_event-reliability-fill-guard-alarm-runbook.md) | | REL-010 | app-service | released | BAT-050, BAT-051, BAT-052, BAT-053, BAT-054 | dcy-034 (차단형 reconcile + sync/verify cold-start) + dcy-035 (WAC 실현손익 운영리포트) + dcy-036 (KIS 인증정보 휴면 배포 — credential_fetch_enabled=OFF) — M3 통합 릴리즈. 배포 revision `314047b`(2026-06-30). verify ImportError 핫픽스 `51cc3cc` 포함. | [rel-010](rel-010_20260629_reconcile-coldstart-wac-report-credential-dormant.md) | +| REL-011 | app-service | draft | BAT-057 | dcy-037 (operator broker truth / managed non-holding divergence hotfix) — **M5 trex-core P0 release**. Source pin `6d90f89`; production daemon restart와 read/dry-run smoke만 대상이며 `sync --live`, config activation, DB migration은 별도 gate. | [rel-011](rel-011_20260716_m5_operator-broker-truth-hotfix.md) | diff --git a/docs/releases/rel-011_20260716_m5_operator-broker-truth-hotfix.md b/docs/releases/rel-011_20260716_m5_operator-broker-truth-hotfix.md new file mode 100644 index 0000000..fa6f12e --- /dev/null +++ b/docs/releases/rel-011_20260716_m5_operator-broker-truth-hotfix.md @@ -0,0 +1,83 @@ +# REL-011: M5 trex-core operator broker truth hotfix + +- Status: **Draft** +- Profile: `app-service` +- Target window: M5 장외 배포 윈도우 (승인 후) +- Owner: 팀장 / 운영팀 +- Included batch: **BAT-057** (`REQ-119`, `REQ-120`, `REQ-121`, `REQ-122`) +- Source discovery: `dcy-037_20260714_operator-broker-truth-and-managed-slot-divergence-hotfix.md` +- Project control card: `★M5 core release: operator broker truth hotfix (BAT-057 / REL-011)` — Project #7, `P0`, `Release-Pending` + +## Release intent + +`credential_fetch_enabled=true` KIS 인스턴스에서 daemon과 운영자 `sync`/`verify`가 동일한 broker credential source와 holding truth를 사용하게 한다. KIS balance/token/auth/transport 실패를 성공한 빈 balance로 축소하지 않고 fail-loud로 종료하며, managed slot이 없는 broker holding과 managed non-holding divergence를 구분해 자동 보정 없이 보존한다. + +이 릴리즈는 M5의 trex-core 선행 배포다. `portfolio-hub` 및 `trex-web`의 M5 배포 게이트와는 별도 release artifact지만, M5 release train의 필수 구성요소로 함께 추적한다. + +## Source and baseline + +| Item | Evidence | +| --- | --- | +| Release source pin | `6d90f8951dbf354eb41301492d0bcaf0af24d882` (`main`; BAT-057 requirement-implementation confirmation 포함) | +| Runtime implementation | PR #42 merge `94e148940adb008db0bbd215052a1e984f7c566b` | +| Prior operational core baseline | Project #7 M4 evidence: `7845fbe` (배포 당일 실제 checkout SHA를 다시 캡처해야 하며, 이를 현 운영 상태의 추정값으로 사용하지 않는다) | +| Batch gate | BAT-057 `confirmed` (`confirm-batch-verification`, 2026-07-15); independent QC `PASS-WITH-NOTES`, acceptance blocker 0 | +| DB/dependency delta from M4 baseline | `pyproject.toml` 및 persistence migration 변경 없음 | +| Wire delta | AMQP 및 portfolio-hub external wire contract 변경 없음; `docs/interface-contract.md`에는 broker-read failure/reconciliation boundary만 명문화 | + +## Included scope + +1. daemon, `sync`, `verify`의 공통 broker provider를 통한 fetched credential source parity. +2. fetched credential read 실패 시 무음 env/config fallback 금지(명시 break-glass만 예외), env-only 및 Paper 경로 회귀 보존. +3. KIS balance 인증·권한·transport·malformed response·broker rejection을 `BrokerBalanceError`로 fail-loud 처리. 실패는 CLI exit `1`이며 정상 empty balance와 구별한다. +4. `unmanaged_position`과 instance-scoped `managed_non_holding_divergence` 분류. 이 분류는 자동 주문, 자동 청산, slot 생성, slot/warning write를 하지 않는다. +5. 안전한 source mode/label 관찰성 및 remediation은 별도 release gate라는 운영 문서 정합. + +## Explicitly excluded + +- `sync --live --yes` 실행, target portfolio 선택, 자동 remediation 및 실제 slot/ledger/broker write. +- `credential_fetch_enabled` 또는 break-glass 설정의 변경·활성화. 배포 전후 해당 인스턴스 설정은 동일해야 한다. +- KIS key/token, account identifier, DSN, portfolio-hub token의 출력·기록·수집. +- PostgreSQL schema migration, dependency upgrade, AMQP topology/wire 변경. +- TVR 및 전략 데몬 배포 범위. + +## Draft verification evidence + +| Check | Result | Evidence / boundary | +| --- | --- | --- | +| Full regression at target source | **PASS** — `807 passed, 47 skipped` | 2026-07-16, repository `.venv/bin/python -m pytest -q` | +| Diff hygiene | **PASS** | `git diff --check 7845fbe..origin/main` | +| CLI surface inspection | **PASS** | `trex-core sync --help`, `trex-core verify --help`; both support per-instance `--config` and `--dry-run` where applicable | +| Batch focused suite | **PASS** — `69 passed, 1 skipped, 1 deselected` | BAT-057 verification evidence; in-process `pika` stub | +| Full Ruff | **Known baseline debt** | target 21 findings; M4 baseline has 22. BAT-057 introduced no new full-suite Ruff failure. Track cleanup separately; do not claim lint-green. | +| Live broker / live PostgreSQL / deployment | **NOT EXECUTED** | Outside batch verification and this draft; release approval and operating evidence required. | + +BAT-057 retains one verification note: fake-driver parity covered the PostgreSQL adapter query/row mapping, but an actual PostgreSQL engine integration fixture was not executed. This is documented evidence debt, not a passed live-database claim. + +## Release approval gates + +Before deployment, all must be true: + +- [ ] Team lead confirms this document, BAT-057 status, target SHA, and no unreviewed source delta. +- [ ] Operations captures the actual currently deployed core revision, instance identifier, supervisor method, and rollback revision; secrets are redacted. +- [ ] Operations confirms the deployment is in an approved 장외 window and strategy/operator owners have been notified of the daemon restart. +- [ ] Operations confirms `credential_fetch_enabled` and break-glass state will not change as part of this release. +- [ ] Operations confirms source checkout is clean and target is exactly `6d90f8951dbf354eb41301492d0bcaf0af24d882`. +- [ ] User/approver authorizes the release execution. A read-only broker smoke is authorized separately from any `sync --live` action. + +## Rollout summary + +1. Capture current revision and existing instance configuration fingerprint (without secrets). +2. Fetch and check out the pinned target source; confirm no migration or dependency action is required by source diff. +3. Stop the existing trex-core daemon using the host’s approved supervisor procedure, then start the same approved instance configuration with the target source. +4. Confirm startup completion, RabbitMQ topology readiness, and no `ERROR`, `CRITICAL`, or traceback in the deployment-window logs. +5. Run only the read/dry-run smoke steps in `docs/runbooks/rel-011-m5-operator-broker-truth-hotfix-deployment.md`. +6. If a failure occurs, stop immediately, restore the captured pre-deploy revision, restart with the unchanged configuration, and collect redacted evidence. + +## Rollback boundary + +Rollback target is the **actual pre-deploy revision captured in the operational preflight**, not an assumed SHA. Since this release adds no migration or dependency change, rollback is source restoration plus daemon restart using the unchanged configuration. Do not delete or alter database data as a rollback action. + +## Next gate + +This artifact remains **Draft / Release-Pending** until operations preflight and user release approval. It does not authorize deployment, broker access, live sync, configuration activation, or remediation by itself. diff --git a/docs/runbooks/rel-011-m5-operator-broker-truth-hotfix-deployment.md b/docs/runbooks/rel-011-m5-operator-broker-truth-hotfix-deployment.md new file mode 100644 index 0000000..1adb46d --- /dev/null +++ b/docs/runbooks/rel-011-m5-operator-broker-truth-hotfix-deployment.md @@ -0,0 +1,144 @@ +# REL-011 M5 trex-core operator broker truth hotfix — deployment runbook + +- Release: `REL-011` +- Target source: `6d90f8951dbf354eb41301492d0bcaf0af24d882` +- Runtime implementation: BAT-057 / PR #42 merge `94e148940adb008db0bbd215052a1e984f7c566b` +- Execution owner: 운영팀 +- Approval required: team lead review + user release approval +- Safety classification: production daemon restart; no DB migration; broker-read smoke only + +> Do not paste credentials, tokens, account numbers, DSNs, `.env` contents, raw KIS responses, or full command lines containing secrets into the evidence log. Use `[REDACTED]`. + +## 1. Scope and hard stops + +Allowed after release approval: + +- Pinned source checkout, existing trex-core daemon stop/start, startup log inspection. +- Existing approved instance configuration used without semantic changes. +- `sync --all --dry-run` and `verify` as broker-read/CLI smoke checks. + +Not allowed in this runbook: + +- `sync --live`, `--yes` with a live write, `enter`, `exit`, `cancel`, or any automated remediation. +- Changing `credential_fetch_enabled`, `TREX_KIS_BROKER_BREAK_GLASS`, broker mode, instance key, portfolio-hub endpoint, or secrets. +- Database schema migration, manual DB update/delete, AMQP topology change, or strategy daemon deployment. + +If any prohibited action appears necessary, stop and return to the release approver. + +## 2. Preflight — record before modifying the host + +1. Confirm the approved release, target SHA, and approved 장외 window. +2. From the operating checkout, capture only redacted metadata: + + ```bash + pwd + git status --short + git rev-parse HEAD + git rev-parse --abbrev-ref HEAD + ``` + + - Record the exact pre-deploy revision as `ROLLBACK_REVISION`. + - If the checkout is dirty or target source cannot be verified, **stop**. + +3. Identify the active instance configuration and process supervisor without printing secrets. Confirm the existing config’s `credential_fetch_enabled` and break-glass state will remain unchanged. +4. Confirm the expected process command remains the established runtime form: + + ```bash + .venv/bin/trex-core-daemon --config + ``` + +5. Confirm target/source characteristics from a clean checkout: + + ```bash + git fetch origin + git show -s --format='%H %s' 6d90f8951dbf354eb41301492d0bcaf0af24d882 + git diff --name-only "$ROLLBACK_REVISION" 6d90f8951dbf354eb41301492d0bcaf0af24d882 -- pyproject.toml trex_core/adapters/persistence/migrations + ``` + + Expected for the reviewed M4 baseline: no dependency or migration path. If actual output differs, **stop** and request lead review; do not infer safety from this draft. + +6. Ensure the deployment host’s virtual environment has the existing runtime dependencies. Do not run dependency upgrades as an implicit part of this release. + +## 3. Deploy source and restart daemon + +Use the host’s approved supervisor procedure. The following expresses the source boundary, not a replacement for host-specific service management: + +```bash +git fetch origin +git checkout --detach 6d90f8951dbf354eb41301492d0bcaf0af24d882 +# Stop the existing trex-core daemon through the approved host supervisor. +# Start exactly one daemon with the unchanged approved instance config. +.venv/bin/trex-core-daemon --config +``` + +Record, with sensitive values redacted: + +- checkout SHA; +- prior process stop confirmation; +- new process identifier or supervisor status; +- selected instance key (not account details); +- startup log interval and log location. + +## 4. Startup acceptance + +Before any CLI smoke, confirm: + +- the daemon completed startup and RabbitMQ topology declaration; +- worker threads are running according to the instance profile; +- no `ERROR`, `CRITICAL`, or traceback appears in the post-restart interval; +- the daemon is using the unchanged configuration mode. Source evidence may show only safe mode/label (`fetched`, `env`, or `break_glass`), never credential payload or account number. + +Any KIS credential-resolution or balance-read failure must be treated as a failure; BAT-057 intentionally prevents treating it as a normal empty broker balance. + +## 5. Read-only/dry-run smoke + +Run against the same explicit approved configuration. These calls may read the configured broker and database but must not write a slot, warning, broker order, or ledger record. + +```bash +.venv/bin/trex-core sync --all --dry-run --config --json +.venv/bin/trex-core verify --config --json +``` + +Acceptance: + +- Commands either succeed with sanitized source/balance evidence, or fail loudly with safe error code/message. +- A failure must not be reinterpreted as an empty balance or “zero quantity” condition. +- For `unmanaged_position` or `managed_non_holding_divergence`, record classification only and stop for triage; no remediation is performed. +- Never add `--live` or `--yes` in this runbook. + +## 6. Rollback + +Trigger rollback for any daemon startup failure, unexpected source-mode change, unexpected credential fetch/fallback behavior, broker-read failure not safely surfaced, AMQP connectivity regression, or smoke behavior inconsistent with BAT-057’s fail-loud/no-auto-remediation contract. + +```bash +# Stop the new daemon via the approved host supervisor. +git checkout --detach "$ROLLBACK_REVISION" +# Restart with the same unchanged approved configuration via the supervisor. +``` + +Then confirm the previous daemon revision is running and collect redacted logs. Do not run database rollback commands; REL-011 introduces no migration. + +## 7. Evidence record template + +```text +Release: REL-011 +Approved by / timestamp: [REDACTED AS NEEDED] +Window: [REDACTED] +Host identity: [REDACTED] +Instance key: [REDACTED] +Pre-deploy revision (ROLLBACK_REVISION): +Target revision: 6d90f8951dbf354eb41301492d0bcaf0af24d882 +Configuration mode unchanged: yes/no (credential_fetch_enabled / break-glass values not recorded) +Daemon stop/start evidence: +Startup log interval: +Startup acceptance: pass/fail +sync --dry-run result: pass/fail + sanitized exit code/output summary +verify result: pass/fail + sanitized exit code/output summary +Unexpected divergence classification: none / unmanaged_position / managed_non_holding_divergence +Rollback performed: no / yes (reason and restored SHA) +Operator: [REDACTED] +``` + +## 8. Completion criteria + +REL-011 may move from `Release-Pending` only after the exact target revision, restart evidence, startup acceptance, dry-run smoke result, verify result, and rollback disposition are reviewed by the team lead. Production live sync remains a separate approval gate even after REL-011 is released.