# 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:

```sh
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`.