# HWLAB Architecture Reference

HWLAB is the hardware lab runtime and control plane for DEV-first MVP work.
The current P0 direction is fixed by `DC-DCSN-P0-2026-003` and
[pikasTech/HWLAB#78](https://github.com/pikasTech/HWLAB/issues/78): prove the
M3 virtual hardware trusted loop before broadening the product surface.

## MVP Boundary

- Environment: `dev` on G14 for MVP runtime work; `prod` on G14 exists as the GitOps-controlled production namespace and public FRP surface.
- Current DEV Cloud Web entry: `http://74.48.78.17:17666/`.
- Current DEV API/edge entry: `http://74.48.78.17:17667/`.
- Current PROD Cloud Web/API entries: `http://74.48.78.17:18666/` and `http://74.48.78.17:18667/`.
- Legacy public `:16666/:16667`, `:6666`, and `:6667` are historical or internal-port surfaces and must not be used as current browser or API acceptance targets.
- UniDesk may support scheduling, CI, or CD. It is not a HWLAB runtime
  substitute.
- M3 mutating proof remains DEV-first; PROD presence is verified through GitOps, Argo sync, Deployment readiness and public health, not through hardware mutation.

## Runtime Shape

Current service ownership and v0.2 keep/remove decisions are authoritative in
[spec-v02-services.md](spec-v02-services.md). The current G14 runtime path is:

```text
browser or CLI
-> master edge / frp public ports
-> G14 hwlab-dev or hwlab-prod namespace
-> HWLAB cloud/runtime services
-> gateway, simulators, patch panel, agent services
```

For M3 hardware proof, the required runtime participants are:

- two distinct `hwlab-box-simu` identities;
- two distinct `hwlab-gateway-simu` identities;
- one `hwlab-patch-panel` that owns the route decision.

真实设备目标以 `device-pod` 作为运行时能力单元。`device-pod`
统一封装 `deviceTarget`、`debugInterface`、`projectWorkspace` 和
`ioInterface` 四要素，并通过拆分的 debug/io 接口提供受控 REST/job
能力；正式 profile authority、REST/job 和服务部署规格见
[spec-device-pod.md](spec-device-pod.md)。

`v0.2` 用户和权限管理规格只保留 `admin` 和 `user` 两类角色：code agent
session 归属于创建用户，device pod 由 `admin` 管理并按用户授权，授权即全权限；
Kubernetes 只做运行时隔离和资源兜底，不承载最终用户权限。权威口径见
[spec-user-access.md](spec-user-access.md)。

## M3 Trusted Loop

M3 DEV-LIVE requires this specific path:

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

The pass evidence must include operation, trace, audit, and evidence
identifiers tied to the same loop. Direct box loopback, front-end state edits,
UniDesk substitution, fixture output, and local-only smoke output are not M3
DEV-LIVE.

The detailed step order and failure classes are authoritative in
[m3-loop-rollout-runbook.md](m3-loop-rollout-runbook.md).

## Evidence Labels

Use the labels below consistently in docs, reports, CLI output, and Cloud Web:

| Label | Meaning |
| --- | --- |
| `SOURCE` | Repository source, contracts, manifests, fixtures, or checked-in reports. |
| `LOCAL` | Localhost or in-process smoke result. |
| `DRY-RUN` | No-mutation plan or fixture-backed preview. |
| `DEV-LIVE` | Observation from the real DEV route for the exact component or loop claimed. |
| `BLOCKED` | Missing, stale, unsafe, or not-yet-authorized evidence/action. |

Only `DEV-LIVE` can support live runtime claims, and only the full M3 loop can
support M3 PASS. Edge health, Cloud Workbench polish, artifact reports, and
desired-state plans are support signals until joined with the required loop
evidence.

Code Agent chat 证据单独分级：只有真实同源 `/v1/agent/chat`
`completed` 响应可以证明 chat reply readiness；provider credential gap
必须保持 `BLOCKED`。它不能升级为 M3、M4、M5 或硬件闭环验收，判定细则见
[code-agent-chat-readiness.md](code-agent-chat-readiness.md)。

## Stable Sources

- [pikasTech/HWLAB#7](https://github.com/pikasTech/HWLAB/issues/7): current
  board and priority status.
- [pikasTech/HWLAB#78](https://github.com/pikasTech/HWLAB/issues/78): M3
  decision and prompt/review guardrails.
- [dev-runtime-boundary.md](dev-runtime-boundary.md): G14 DEV/PROD and v0.2 runtime boundary.
- [spec-v02-services.md](spec-v02-services.md): v0.2 microservice keep/remove and dependency boundary.
- [spec-v02-documentation-governance.md](spec-v02-documentation-governance.md): root README and legacy process document migration.