# HWLAB DEV Edge Health

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

```sh
node scripts/dev-edge-health-smoke.mjs --live --report /tmp/hwlab-dev-gate/report.json
```

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:16667/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. Runtime health additionally reports redacted DB readiness layers:
`configReady`, `envInjected`, `endpointSource`, `connectionAttempted`,
`connectionResult`, and `liveConnected`. It must not expose a connection
string, token, password, DB host, username, 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=disable`.
- Runtime TCP dial target: the redacted host parsed from
  `HWLAB_CLOUD_DB_URL`, reported as `endpointSource="secret-url-host"`.

`cloud-api-db` is only an optional desired alias. Until this repo owns the
Service plus Endpoint or EndpointSlice manifests and rollout/apply contract, it
is not a readiness authority, is not the TCP probe target, and a missing alias
must not reverse-fail live DB success from the Secret URL host.

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 attempted, the gate remains blocked with
`connectionResult: "not_attempted"`. When a probe is attempted but
`liveConnected` is false, the gate remains blocked/degraded with the redacted
connection classifier. `connectionResult: "dns_error"` with
`classification: "dns_resolution_failed"` means DB endpoint DNS failed from the
cloud-api runtime for the Secret URL host. Env presence alone is not live DB
evidence.

The Code Agent provider Secret for #143 is a separate blocker. The edge-health
report may record only key-presence evidence for
`hwlab-code-agent-provider/openai-api-key` and runtime error classification such
as `provider_secret_missing`; it must not read or print provider Secret values.
Do not collapse this #143 provider Secret gap into the DB live blocker.

## Route Classification

The smoke classifies failures into these blockers:

- `frp_blocker`: public `:16667` is unavailable and frps control or tunnel
  health ports also refuse connections.
- `edge_proxy_blocker`: frps is reachable, but public `:16667` 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, returns an HTTP error, or reports DB env injected without a
  live DB connection.

## Machine-Readable Diagnosis

Blocked `frp_blocker` and `edge_proxy_blocker` reports now include a
`diagnosis` object in `/tmp/hwlab-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 `/tmp/hwlab-dev-gate/dev-edge-health.json` records a
read-only live run where public `http://74.48.78.17:16667/health/live` returned
HWLAB DEV health from `hwlab-cloud-api`, DB config was present, and runtime
health attempted a redacted TCP DB probe. The probe was not connected:
`connected=false`, `liveConnected=false`, `liveDbEvidence=false`,
`connectionResult="dns_error"`, and
`classification="dns_resolution_failed"`. This is a DB live readiness blocker
for #49, not proof that DB is connected.

The same report records the #143 Code Agent provider Secret gap separately as
`provider_secret_missing` when key-presence evidence for
`hwlab-code-agent-provider/openai-api-key` is absent. DB live readiness,
provider-backed Code Agent chat, M3 hardware trusted-loop proof, M4 live agent
loop, and M5 DEV-LIVE acceptance remain separate evidence layers.

## DEV FRP Contract

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