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

# 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 target-runtime trusted-loop acceptance path, not a generic deployment or
front-end acceptance path. The target Web/API boundary must come from the current issue/CLI node + lane status.

- Public frontend boundary: current target Web URL.
- Public API/edge boundary: current target API URL.
- 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.yaml` 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.

After the DB and Code Agent provider unblock, the next acceptable M3 step is
still not a blind live write. Run the no-write source contract first:

```sh
node scripts/dev-m3-hardware-loop-smoke.mjs --dry-run
```

The dry-run output is `DRY-RUN` evidence. It must list the live write
preconditions, the exact endpoints a later live run would call, and the
required evidence fields while keeping `liveOperation.status: "not_run"`.
Only an explicitly approved live window may use:

```sh
node scripts/dev-m3-hardware-loop-smoke.mjs --live --confirm-dev --expect-non-prod
```

The live command remains DEV-only and must stop before mutation unless the two
box-simu identities, two gateway-simu identities, and patch-panel-owned M3
wiring are all observed.

## Manual Acceptance Steps

| Step | What to observe | Must have evidence | Failure class | Must not misread |
| --- | --- | --- | --- | --- |
| 1 | Confirm the public target boundary and frozen route. | Current target Web URL for frontend, current target API URL 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 `:16666/:16667`, legacy `:6666`, public `:6667`, G14 DEV, v0.2, or another lane as the current acceptance target. |
| 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.