pikasTech-HWLAB/docs/reference/m3-loop-rollout-runbook.md

M3 Loop Rollout Runbook

This reference is support / diagnostics / contract for the HWLAB P0 M3 virtual hardware trusted loop only. It is not P0 live evidence and it must not relabel SOURCE / LOCAL / DRY-RUN / fixture output as DEV-LIVE.

M3 Loop Boundary

• P0 scope: 2 x hwlab-box-simu, 2 x hwlab-gateway-simu, 1 x hwlab-patch-panel.
• Accepted chain for live M3 proof: DO1 -> patch-panel -> DI1.
• Current public endpoints: browser/frontend http://74.48.78.17:16666/ and API/edge/live http://74.48.78.17:16667/.
• Legacy public ports :6666 and :6667 are historical / deprecated only.
• pikasTech/HWLAB#63 remains a known CD blocker until suspended Job immutable apply is fixed.

Source Of Truth

deploy/deploy.json is the deploy intent source. deploy/artifact-catalog.dev.json is the artifact identity source. No shell scrollback, issue comment, or report fixture is authoritative over those two files.

Fact	Read From	Notes
source commit	deploy/deploy.json.commitId and deploy/artifact-catalog.dev.json.commitId	They must match.
image tag	deploy/deploy.json.services[].image and deploy/artifact-catalog.dev.json.services[].imageTag	The tag must stay tied to the source commit.
digest	deploy/artifact-catalog.dev.json.services[].digest	Real digests come only from publish evidence; otherwise keep not_published.
public endpoint	deploy/deploy.json.publicEndpoints.*.url and deploy/deploy.json.endpoint	Current endpoints are 16666/16667; do not backslide to legacy ports.
frp	deploy/deploy.json.frp.proxies[]	Derive proxy name, local service, local port, and remote port from the manifest.
k3s service	deploy/deploy.json.k3s.serviceMappings[]	Derive service name, namespace, port, and targetPort from the manifest.
health path	deploy/deploy.json.health.path and deploy/deploy.json.services[].healthPath	Must stay on /health/live.

Rollout Support

Use this order for M3 loop support work:

1. Render the manifest contract and compare it with the artifact catalog.
2. Verify the M3 inventory cardinality for the two boxes, two gateways, and one patch-panel.
3. Check that the current public endpoints stay on 16666/16667.
4. Confirm the health path is /health/live.
5. Record any manual hotfix facts back into the issue, PR, and runbook before closing the task.

Recommended checks:

node scripts/deploy-contract-plan.mjs --pretty
node scripts/deploy-contract-plan.mjs --check
node scripts/validate-dev-m3-cardinality.mjs
npm run docs:validate:m3-rollout

These checks are support only. They do not apply to DEV, do not touch PROD, do not restart services, and do not prove live M3 acceptance.

Rollback Support

If a manual hotfix or rollback is required, record the following before the task closes:

• source commit and branch or PR;
• image reference, image tag, and digest;
• public endpoint and whether it was read-only or routed;
• FRP proxy name and ownership;
• k3s service mapping and ownership;
• health path used for verification;
• any field that diverged from deploy/deploy.json or the artifact catalog.

Rollback support must keep the live chain honest. If the chain was not actually DO1 -> patch-panel -> DI1, do not claim live M3. Only write support, diagnostics, or contract evidence.

Prohibited Actions

• Do not treat this runbook as a general console or PROD flow.
• Do not deploy or smoke PROD.
• Do not read, print, or infer secrets, tokens, kubeconfig, or tunnel credentials.
• Do not restart Code Queue, backend-core, or any runtime service from the runner.
• Do not run heavyweight e2e or destructive hardware tests.
• Do not bypass pikasTech/HWLAB#63 and then claim CD is green.
• Do not promote SOURCE / LOCAL / DRY-RUN / fixture output to DEV-LIVE.