Code Queue Review
121 lines
5.5 KiB
Markdown
121 lines
5.5 KiB
Markdown
# 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.
|
|
|
|
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 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.
|