# HWLAB DEV Edge Health

This check is DEV-only and targets the frozen endpoint:

```sh
node scripts/dev-edge-health-smoke.mjs --live --write-report
```

The smoke is read-only. It does not touch PROD, restart services, read
secrets, or substitute UniDesk backend/provider-gateway/microservice-proxy for
HWLAB runtime.

## Health Evidence

`GET http://74.48.78.17:6667/health` must return HWLAB DEV JSON with:

- `serviceId` for the HWLAB service answering the request;
- `environment: "dev"`;
- `commit` evidence;
- `image` evidence;
- `service` evidence.

`hwlab-cloud-api` also serves `GET /health/live` for k3s probes and edge
forwarding checks.

`db` in the cloud-api health payload is a redacted configuration gate. It
reports required env names, presence, missing names, and Secret reference names
only. It must not expose a connection string, token, password, or claim fixture
output as live DB evidence.

Required DEV DB config names:

- `HWLAB_CLOUD_DB_URL` from Secret reference
  `hwlab-cloud-api-dev-db/database-url`.
- `HWLAB_CLOUD_DB_SSL_MODE=require`.

When the Secret/env is absent, the health JSON should keep
`db.connected: false`, set `db.status: "blocked"`, and list the missing env
names so gate reports can identify `cloud-api-db-health-gate`. When the env is
present but no live DB probe is connected, `db.status` remains `"degraded"` and
`db.ready` remains `false`; env presence alone is not live DB evidence.

## Route Classification

The smoke classifies failures into these blockers:

- `frp_blocker`: public `:6667` is unavailable and frps control or tunnel
  health ports also refuse connections.
- `edge_proxy_blocker`: frps is reachable, but public `:6667` refuses.
- `k3s_service_blocker`: k3s is observable but HWLAB DEV services/endpoints are
  missing.
- `dns_port_firewall_blocker`: public endpoint times out or cannot be resolved
  as a port/network path.
- `app_health_blocker`: public HTTP reaches an app but health JSON is wrong,
  missing evidence, or returns an HTTP error.

## Machine-Readable Diagnosis

Blocked `frp_blocker` and `edge_proxy_blocker` reports now include a
`diagnosis` object in `reports/dev-gate/dev-edge-health.json` with:

- `likelyLayer`: the most likely broken layer, such as `master-edge/frps`;
- `confidence`: coarse confidence for the diagnosis;
- `likelyCause`: a single-sentence blocker summary;
- `evidence`: the TCP probes that support the diagnosis;
- `notProven`: layers this probe did not rule out;
- `nextTask`: the smallest read-only follow-up or ops action.

## Current Blocker

The committed report at `reports/dev-gate/dev-edge-health.json` records a
read-only live run where:

- public `74.48.78.17:6667` returned `ECONNREFUSED`;
- frps control `74.48.78.17:7000` returned `ECONNREFUSED`;
- tunnel health `74.48.78.17:7402` returned `ECONNREFUSED`;
- `kubectl` was not installed in this runner, so D601 k3s service state was not
  observable from here.

Classification: `frp_blocker`. The master frps endpoint is not reachable from
the runner, so the edge proxy and downstream app health cannot be proven through
the public DEV route yet.

## DEV FRP Contract

`deploy/frp/frps.dev.toml` reserves public `6667` as a TCP `remotePort` for
`hwlab-dev-edge-proxy`. Do not bind `vhostHTTPPort = 6667` in the same frps
config; that collides with the TCP proxy and can keep the DEV route from
registering cleanly.