# Cloud API Runtime

The L1 `hwlab-cloud-api` runtime is a minimal local HTTP/JSON-RPC service. It
does not deploy to DEV or PROD and does not claim live database persistence.

## Local Smoke

Run:

```sh
node scripts/cloud-api-runtime-smoke.mjs
```

The smoke starts `cmd/hwlab-cloud-api` on `127.0.0.1` with an ephemeral port
and verifies:

- `GET /health` reports `status: "degraded"` when live DB persistence is not
  connected.
- The DB contract reports required env names, redacted Secret refs, env
  injection, connection attempt status, connection result, `liveConnected`,
  `liveDbEvidence`, and redaction/safety fields without exposing DB URL or
  secret values.
- `gateway.session.register`, `box.resource.register`,
  `box.capability.report`, `hardware.invoke.shell`, `audit.event.query`, and
  `evidence.record.query` round-trip through the same runtime store.
- Shell invoke requests are accepted as recorded cloud operations but report
  `dispatchStatus: "not_connected"` until a real gateway shell adapter exists.
- Audit and evidence records use the protocol schema field names.

## Persistence Boundary

The current runtime store is process-local memory:

- `runtime.adapter: "memory"`
- `runtime.durable: false`
- `runtime.status: "degraded"`

This is intentional for L1. If `HWLAB_CLOUD_DB_URL` and
`HWLAB_CLOUD_DB_SSL_MODE` are absent, health reports `db.status: "blocked"`.
If both env vars are present, cloud-api attempts a short read-only TCP
connection to the DB endpoint from the injected runtime env. The health payload
keeps all endpoint details redacted and reports only:

The source-controlled DEV DNS contract for that endpoint is
`cloud-api-db.hwlab-dev.svc.cluster.local:5432`. The actual connection string
still comes from `hwlab-cloud-api-dev-db/database-url`; source records only the
non-secret host/service/namespace/port contract.

- `db.configReady`: required env names are present.
- `db.connectionAttempted`: the runtime tried the live connection path.
- `db.connectionResult`: redacted classifier such as `connected`, `refused`,
  `timeout`, `dns_error`, `invalid_url`, or `unsupported_protocol`.
- `db.liveConnected`: the TCP connection completed.
- `db.liveDbEvidence`: true only when the live connection completed; env
  presence, fixtures, and disabled probes must keep this false.
- `db.redaction` and `db.safety`: confirm values/endpoints are redacted and
  secret material was not read by the health path.
- `db.ready`: currently aliases `db.liveConnected`.

Env presence alone is not treated as green. If the runtime has env injection
but `db.connectionAttempted` is false, `db.liveConnected` is false, or
`db.liveDbEvidence` is false, the gate must stay blocked/degraded with the
reported blocker.

Fixture: `fixtures/cloud-api-runtime/minimal-runtime.json`.