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:

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:

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:

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:

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.

5.6 KiB Raw Permalink Blame History