trex-core/docs/runbooks/m5-coordinated-release-train-readiness.md

M5 coordinated release train — deployment readiness and execution control

• Status: Released
• Train confirmation: 2026-07-17 KST — lead reconciliation of the M5 common release evidence and individual release evidence
• Date: 2026-07-16
• Coordinator: TREX lead
• Scope: trex-core REL-011, portfolio-hub REL-004, trex-web REL-002
• Authority: This document coordinates release order and shared stop criteria. It does not replace each service's release document, runbook, release approval, or operator-owned deployment procedure.

1. Decision statement

The M5 coordinated train is Released. The lead reconciled the M5 common evidence handoff with the individual, release-specific records: trex-core REL-011 is released; portfolio-hub REL-004 is released with a documented non-blocking test-fixture follow-up; and trex-web REL-002 is released. The later trex-core REL-012 is a separately released post-M5 hotfix and is not a prerequisite for this M5 decision.

No release is inferred merely from source publication: this closure relies on the recorded service-specific operational evidence and decisions cited in the inventory below. Deferred follow-ups remain owned by their respective services and do not reopen the completed M5 train.

2. Release inventory and evidence

Order	Service / release	Pinned application source	Evidence supporting an execution request	Non-negotiable outstanding gate
1	trex-core REL-011 / BAT-057	6d90f8951dbf354eb41301492d0bcaf0af24d882 (runtime PR #42 merge 94e148940adb008db0bbd215052a1e984f7c566b)	Released — Justin Ko approval 32675, rollback SHA 7845fbe, controlled daemon restart, startup health, and read-only smoke captured in REL-011 execution evidence	No remaining core release gate; this does not authorize live sync
2	portfolio-hub REL-004 / BAT-024, BAT-025	914b3dc6e6b9e2cbd7068fb30435c83f0581eab5 or reviewed descendant	Released with deferred non-blocking test-fixture follow-up — backup PASS; migration 20260715_0028, schema invariants, 73 → 73 row-count preservation, Supervisor restart, /health 200, db_enabled: true, owner read PASS, non-owner HTTP 403	No train-blocking gate; owner_user_id fixture follow-up remains service-owned
3	trex-web REL-002 / BAT-010	1ec2cf4345310cab0d3468e36b31e0613668b482 or approved descendant	Released — build/runtime install PASS; Supervisor RUNNING on 8004; external /trex/ and sign-in HTTP 200; authenticated portfolio UI/session checks PASS; browser-console JS errors 0	No train-blocking gate; npm audit low/moderate notice remains service-owned

Supporting service documents:

• core: docs/releases/rel-011_20260716_m5_operator-broker-truth-hotfix.md, docs/runbooks/rel-011-m5-operator-broker-truth-hotfix-deployment.md
• portfolio-hub: docs/releases/rel-004_20260715_manual-ledger-api-and-metadata-migration.md, docs/runbooks/rel-004-m5-manual-ledger-deployment-runbook.md
• trex-web: docs/releases/rel-002_20260715_m5-portfolio-ui-theme.md, docs/runbooks/rel-002-m5-portfolio-ui-theme-deployment.md

3. Shared prerequisites before any execution

1. Record an explicit release-window approval for the specific REL; an approved document push is not deployment approval.
2. Record operator, window, target host/environment, source/artifact pin, and the currently working rollback source/artifact before changing a process or database.
3. Confirm the release's source is exactly pinned or a separately reviewed descendant. Never deploy an unpinned branch head.
4. Keep credentials, .env values, tokens, backup contents, bearer headers, and customer/portfolio data out of chat, terminal capture, and release documents.
5. Run only the service-owned runbook commands or the real operator-owned platform procedure. Local test Compose files, guessed systemd commands, and ad-hoc production command substitutions are prohibited.
6. Capture secret-free command exit status, timestamps, PID/rollout state, health/status result, and rollback decision in the corresponding REL evidence table.

4. Coordinated execution order

Step 1 — trex-core REL-011 (independent, urgent broker-truth hotfix)

Execute only after REL-011 approval. Capture the current deployed SHA, update to the pin, use the existing supervisor to restart the core daemon, then perform only the runbook's read-only checks (sync --all --dry-run and verify) against the approved instance. sync --live --yes, slot/order mutation, automatic remediation, and changing credential_fetch_enabled are outside this release.

Proceed to Step 2 only when: the daemon remains healthy, logs show no startup/fatal error, the read-only checks have their expected no-write classification, and no rollback trigger occurs.

Step 2 — portfolio-hub REL-004 (highest-risk: production DB migration)

Execute only after independent REL-004 approval and the backup/DB gates pass. Perform the approved backup and capture Alembic heads/current, active workload/locks, schema state, and row counts. Upgrade exactly to 20260715_0028, prove the four metadata columns/default/not-null/row-count invariants, then use the existing operator-owned rolling deployment procedure. Start with read-only health and existing-read checks; a manual-ledger mutation smoke needs separate explicit approval for a designated non-sensitive test portfolio.

Proceed to Step 3 only when: migration postchecks pass, portfolio-hub health reports db_enabled: true, existing read paths work, authorization checks are correct, and the agreed observation period is clean.

Step 3 — trex-web REL-002 (presentation release after dependencies are healthy)

Before stopping the process, reconcile the actual reverse-proxy upstream with the active deploy script and explicitly record the chosen app port. Stop if /trex is stripped or if the proxy target differs from the selected port. After portfolio-hub is healthy, build and start through scripts/deploy-trex-web.sh, then smoke the reverse-proxy route—not only localhost—for sign-in, portfolio list, safe existing portfolio detail, selected state/table readability, refresh/session, and logs.

5. Stop and rollback boundaries

Release	Stop immediately when	Permitted recovery
core REL-011	missing approval/pin, daemon startup failure, error/no-write barrier failure, unexpected broker mutation risk	use captured pre-release source with the normal supervisor restart; retain all evidence; no live sync as a diagnostic shortcut
portfolio REL-004	missing backup, unknown/branched Alembic state, lock/workload not accepted, migration/schema/null/row-count mismatch, health or authorization anomaly	before success: do not deploy new code; after migration success: roll back only to compatible code and retain additive schema 20260715_0028; no downgrade, column drop, or restore without separate incident approval
web REL-002	unresolved 3000/8004 proxy decision, /trex stripped, build/start failure, sign-in/portfolio regression, material readability regression	stop new process, restore captured known-good revision with the approved script, and recheck /trex, sign-in, portfolio list; no DB rollback applies

6. Release completion rule

A service becomes released only after its own runbook evidence is complete and the lead records confirm-release. Do not mark the M5 train released because a source commit was pushed, a build passed, or another service succeeded.

The coordinated train closes only when all intended service releases have individual evidence and decisions, or when deferred/excluded services are explicitly recorded with rationale and follow-up ownership.

7. confirm-release — M5 train

Released. The intended M5 scope is closed with recorded individual release decisions:

1. trex-core REL-011: released; approval, pin, rollback revision, restart, and dry-run/verify evidence complete.
2. portfolio-hub REL-004: released; its owner_user_id test-fixture item is explicitly deferred and non-blocking.
3. trex-web REL-002: released; proxy port 8004, external /trex route, sign-in, authenticated portfolio flow, and browser-console checks passed.

trex-core REL-012 is recorded separately as a post-M5 hotfix. It does not change M5 scope or the train’s completion decision.