# REL-012: cost-basis canonical parse 및 안전 sync seed 긴급 핫픽스

- Status: **Draft / Release-Pending**
- Profile: `app-service`
- Priority: **urgent**
- Owner: 팀장 / 운영팀
- Included batch: **BAT-058** (`REQ-123`)
- Source discovery: [`dcy-038`](../discovery/dcy-038_20260716_cost-basis-response-contract-and-safe-sync-seeding.md)
- Batch verification: [`BAT-058 verification`](../batches/bat-058_20260716_cost-basis-safe-sync-seed/verification.md) — lead `confirm-batch-verification`, QC-7 `PASS-WITH-NOTES`
- Operations handoff: [`REL-012 deployment request`](../runbooks/rel-012-cost-basis-safe-sync-seed-ops-handoff.md)

## Release intent

portfolio-hub의 기존 cost-basis 응답에서 canonical `cost_basis_per_unit`을 우선 해석하고, broker quantity가 양수인 inactive-slot onboarding에서 WAC/avg_price를 얻지 못하면 live sync가 slot status/qty/avg_price/warning을 쓰지 않은 채 non-zero로 fail-closed하도록 한다. dry-run은 sanitized source/reason과 no-write preview를 제공한다.

## Source publication boundary

| Item | Current evidence | Release constraint |
| --- | --- | --- |
| Remote `origin/main` | `18bd8d9f0b7bb76b08303bbf8743e6ddf916de89` (2026-07-17 fetch) | BAT-058 source is **not included** in this remote revision. |
| BAT-058 candidate | [`81a853a`](https://github.com/fourblocks2020/trex-core/commit/81a853a314391da7a8bc9df5517013c7fd296d61) on `origin/feat/dcy-038-cost-basis-safe-sync-seed` | Reviewed code + BAT/REL/runbook source is published; target remains subject to production approval. |
| Immutable deploy target | [`81a853a`](https://github.com/fourblocks2020/trex-core/commit/81a853a314391da7a8bc9df5517013c7fd296d61) | Published and remote-ref verified 2026-07-17; operations independently re-verifies before execution. |

This document is a release draft and a preflight request only. It does **not** authorize deployment, daemon restart, broker/portfolio access, `sync --live`, database writes, configuration activation, or credential access.

## Included scope

1. `cost_basis_per_unit` canonical priority parsing and approved legacy compatibility chain (`avg_cost` → `wac` → `cost_basis`) only when canonical is absent.
2. Canonical invalid/null/non-numeric/zero/negative values are not silently masked by a legacy value; diagnostic reasons remain sanitized.
3. Inactive slot + positive broker quantity + unavailable WAC: dry-run no-write preview; live non-zero fail-closed with no slot/warning mutation.
4. Existing HOLDING reconciliation remains compatible; sanitized CLI/operator diagnostics preserve `seeded_avg_price`, source, and absence reason.

## Explicit exclusions / no-go

- portfolio-hub API/schema/auth changes, token/config changes, dependency upgrade, DB migration, direct DB edit/delete, AMQP wire/topology change.
- Any `sync --live`, `--yes` live write, automatic remediation, order action (`enter`/`exit`/`cancel`), or target portfolio selection.
- Changing `credential_fetch_enabled`, break-glass mode, instance configuration, endpoint, or secrets.
- Strategy daemon deployment.

A single-target `sync --live --yes` remains a separately approved post-release action even after this source rollout. It must not be used as a deployment smoke shortcut.

## Draft verification evidence

| Check | Result | Evidence / limitation |
| --- | --- | --- |
| Independent QC-7 | **PASS-WITH-NOTES** | Legacy-invalid focused `8 passed, 19 deselected`; affected suite `113 passed`; full suite `833 passed, 47 skipped`; Ruff/compileall/diff hygiene pass. |
| Release-prep full regression | **PASS** | 2026-07-17 delivery worktree: `833 passed, 47 skipped in 1.88s`. |
| Focused Ruff | **PASS** | Changed adapter/reconcile/CLI and relevant tests: `All checks passed!`. |
| Focused compile check | **PASS** | Six changed source/test paths, `compileall -q`, exit `0`. |
| Live broker, live PostgreSQL, production deploy | **NOT EXECUTED** | Outside batch verification and this draft; no claim is made. |
| Source publication | **PENDING** | No immutable remote candidate SHA exists yet. |

## Release approval gates

All items must be satisfied before operations executes the runbook:

- [x] Git-ops published the reviewed source and initial REL/runbook draft; target `81a853a` is remote-ref verified on `origin/feat/dcy-038-cost-basis-safe-sync-seed`.
- [ ] Operations verifies that exact target SHA contains REL-012 and its runbook, and captures the actual deployed revision as `ROLLBACK_REVISION`.
- [ ] User/approver explicitly authorizes production execution and the approved off-market window is recorded.
- [ ] Operations confirms the source checkout is clean; existing runtime configuration and credential/break-glass modes will not change.
- [ ] Operations confirms no dependency or migration delta exists between `ROLLBACK_REVISION` and the exact target SHA.
- [ ] Operations records the approved supervisor method, instance key (redacted as necessary), and post-deploy observation owner.

## Rollout and rollback policy

1. Use the pinned immutable source only; use the host’s existing approved supervisor to restart the same daemon with unchanged approved configuration.
2. After startup acceptance, run only the read/dry-run commands in the REL-012 runbook.
3. Stop and roll back on startup failure, traceback/error regression, unexpected credential/source-mode behavior, unexpected mutation indication, or smoke output that violates the no-write/fail-closed contract.
4. Roll back by restoring the actual captured `ROLLBACK_REVISION` and restarting with unchanged configuration. Do not run database rollback commands, direct DB edits, or live sync.

## Evidence required for `confirm-release`

Operations returns a secret-free record containing: approver/window/operator; `ROLLBACK_REVISION` and target SHA; clean-checkout/preflight result; restart/startup result; dry-run smoke and `verify` exit/status summaries; observed no-write/fail-closed classifications; and rollback disposition. The lead then reviews that evidence before changing REL-012 from Draft / Release-Pending.