# M3 Loop Rollout Runbook

This reference is the human acceptance contract for the M3 virtual hardware
trusted loop. It is the authoritative place for the manual step order, evidence
requirements, failure classes, and misclassification bans used by commanders
and operators.

It does not authorize a real deployment, PROD action, secret read, service
restart, or heavyweight e2e run.

## M3 Loop Boundary

M3 is a DEV-only trusted-loop acceptance path, not a generic deployment or
front-end acceptance path.

- Public frontend boundary: `http://74.48.78.17:16666/`.
- Public API/edge boundary: `http://74.48.78.17:16667/`.
- Historical public `:6666` and `:6667` endpoints are not current acceptance
  targets; internal k3s services may still use `6667`.
- Runtime intent and artifact identity are reviewed through
  `deploy/deploy.json` and `deploy/artifact-catalog.dev.json`.
- Suspended template Job replacement is tracked by
  `pikasTech/HWLAB#63` and must not be confused with M3 loop evidence.

The support / diagnostics / contract surfaces can help operators understand
the runtime, but they do not prove the trusted loop.

Current M3 target shape:

```text
2 x hwlab-box-simu
2 x hwlab-gateway-simu
1 x hwlab-patch-panel
DO1 -> patch-panel -> DI1
```

Do not promote SOURCE / LOCAL / DRY-RUN / fixture output to `DEV-LIVE`.

## M3 MVP Pass Condition

M3 MVP PASS requires the live DEV chain:

```text
res_boxsimu_1:DO1 -> hwlab-patch-panel -> res_boxsimu_2:DI1
```

The evidence must show all of the following:

- two `hwlab-box-simu` identities that are visibly distinct;
- two `hwlab-gateway-simu` identities that are visibly distinct;
- one `hwlab-patch-panel` participant that owns the route decision;
- one operation ID, one trace ID, one audit ID, and one evidence ID that all
  resolve to the same loop;
- no box loopback substitute, no front-end direct state edit, and no UniDesk
  runtime or proxy substitute.

Cloud Web polish, generic console work, artifact reports, and desired-state
planning are support surfaces only. They can help explain the system, but they
do not count as M3 PASS evidence.

## Manual Acceptance Steps

| Step | What to observe | Must have evidence | Failure class | Must not misread |
| --- | --- | --- | --- | --- |
| 1 | Confirm the public DEV boundary and frozen route. | `http://74.48.78.17:16666` for frontend, `http://74.48.78.17:16667` for API/edge, internal `6667` only as a k3s port, and the checked-in docs or checklist that freeze those values. | `environment_blocker` | Do not treat legacy `:6666` or public `:6667` as acceptance targets. |
| 2 | Confirm two box simulators and two gateway simulators are present and distinct. | Two observable `hwlab-box-simu` identities, two observable `hwlab-gateway-simu` identities, their resource/session IDs, and the shared DEV project. | `runtime_blocker` | Do not infer cardinality from one box, one gateway, or fixture-only output. |
| 3 | Confirm one patch panel owns the route. | `hwlab-patch-panel` status, wiring, and the active connection from `res_boxsimu_1:DO1` to `res_boxsimu_2:DI1`. | `runtime_blocker` | Do not accept box loopback, direct box mutation, or a UI state edit as routing proof. |
| 4 | Confirm the live loop operation. | Operation ID, trace ID, audit ID, and evidence ID tied to `res_boxsimu_1:DO1 -> hwlab-patch-panel -> res_boxsimu_2:DI1`. | `runtime_blocker` | Do not promote SOURCE, LOCAL, DRY-RUN, or edge-only evidence to PASS. |
| 5 | Confirm cleanup and containment. | Logs or records showing no leaked worker, gateway, patch-panel, project, or hardware state after the run. | `agent_blocker` | Do not leave cleanup implicit. |

## Failure Classes

- `contract_blocker`: the doc, checklist, or contract files do not parse or
  disagree on frozen names, endpoints, or IDs.
- `environment_blocker`: the public DEV boundary is wrong or confused with a
  legacy endpoint.
- `network_blocker`: the route to the DEV edge, frp, or router cannot be
  observed.
- `runtime_blocker`: the two box simulators, two gateway simulators, patch
  panel, or wiring evidence is missing or contradictory.
- `agent_blocker`: trace, audit, evidence, session, or cleanup records are
  missing or leaked.
- `observability_blocker`: artifact identity, commit, image/tag/digest,
  build source, environment, or health timestamp is missing.
- `safety_blocker`: a prohibited action was attempted.

## Misclassification Bans

- SOURCE, LOCAL, DRY-RUN, fixture-only, and edge-only evidence are support
  signals only.
- Cloud Web polish does not prove M3.
- Generic console work does not prove M3.
- Artifact reports do not prove M3.
- Desired-state plans do not prove M3.
- UniDesk runtime or proxy substitution does not prove M3.

## Validation

This file is validated indirectly by the operator runbook and DEV acceptance
matrix, plus the checklist JSON shape.