# 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 from source tests and does not claim live
database persistence unless both DB readiness and the durable runtime adapter
readiness are live.

## 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.
- `GET /health` reports DB readiness and runtime durable adapter readiness as
  separate components. A memory adapter remains non-durable even when DB env
  fields are present.
- The DB contract reports required env names, redacted Secret refs, env
  injection, connection attempt status, connection result, `liveConnected`,
  `liveDbEvidence`, DNS/TCP/auth/schema readiness layers, 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 default local runtime store is process-local memory:

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

This remains the safe local default. DEV can opt into the durable adapter with
non-secret env flags:

- `HWLAB_CLOUD_RUNTIME_ADAPTER=postgres`
- `HWLAB_CLOUD_RUNTIME_DURABLE=true`

The Postgres adapter uses `HWLAB_CLOUD_DB_URL` from
`hwlab-cloud-api-dev-db/database-url`; source records only the Secret reference
and non-secret DNS contract. `HWLAB_CLOUD_DB_SSL_MODE` is the runtime authority
for DB TLS mode; if it is `disable`, the adapter strips URL `sslmode` query
parameters before opening the Postgres pool so stale Secret URL parameters
cannot override the DEV SSL contract. The adapter reports `runtime.durable: true`
only after the configured adapter proves all durable gates through read-only
runtime checks:

- auth/query access to the configured DB path;
- required runtime table and column schema;
- the source-controlled migration ledger row for
  `0001_cloud_core_skeleton` / `runtime-durable-postgres-v1`;
- read readiness against the runtime tables used by audit and evidence
  queries.

If DB SSL negotiation, auth, schema, migration, or read readiness is missing, `/health/live`
stays degraded with `runtime.durable: false`, `runtime.durableRequested: true`,
and a runtime blocker such as `runtime_durable_adapter_ssl_blocked`,
`runtime_durable_adapter_auth_blocked`, `runtime_durable_adapter_schema_blocked`, or
`runtime_durable_adapter_migration_blocked`. Fixture data and env presence are
never promoted to `runtime.liveRuntimeEvidence`.

When the Postgres durable adapter is selected or requested, JSON-RPC
`audit.event.query` and `evidence.record.query` must also honor that durability
gate. If auth, schema, migration, durability-query, or table read-query evidence
is blocked, the method returns a JSON-RPC error with redacted blocker data such
as `adapter: "postgres"`, `durableRequested: true`,
`liveRuntimeEvidence: false`, `secretMaterialRead: false`, and the classified
blocker. It must not
return `events: []`, `records: []`, or `count: 0` on a blocked durable read.
Empty successful result sets are valid only after the durable adapter has
completed the read and the matching durable table rows are actually absent.

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 runtime DB readiness authority is the host parsed from the injected
`HWLAB_CLOUD_DB_URL` Secret value. Health reports this as
`db.endpointSource: "secret-url-host"` without printing the host, username,
password, or full URL. The `cloud-api-db` name is only an optional future alias;
it is not the TCP probe target and a missing alias must not reverse-fail live DB
success from the Secret URL host.
`.invalid` hosts, including `hwlab-dev-db.invalid`, are forbidden as DEV
runtime targets and may be used only as negative fixtures.

- `db.configReady`: required env names are present.
- `db.endpointSource`: `secret-url-host`, the authoritative redacted TCP dial
  target parsed from `HWLAB_CLOUD_DB_URL`.
- `db.optionalPublicDnsAlias`: diagnostic metadata for the non-authoritative
  `cloud-api-db` alias; `requiredForReadiness` and `usedForProbe` stay false.
- `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.readinessLayers`: records DNS, TCP, auth, and schema status separately so
  DNS/TCP repair cannot be confused with authenticated schema readiness.
- `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`.

## Code Agent Provider Boundary

`hwlab-cloud-api` supports OpenAI Responses for the Code Agent chat endpoint.
DEV source contracts require `OPENAI_API_KEY` from Secret
`hwlab-code-agent-provider/openai-api-key` and
`HWLAB_CODE_AGENT_OPENAI_BASE_URL` through the DEV egress/proxy URL. Runtime
health and `/v1` may report provider status, missing env names, Secret ref
names, model, and redacted egress status, but must never print the API key or a
Bearer token.