pikasTech-HWLAB/docs/cloud-api-runtime.md

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:

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, and liveConnected 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:

• 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.ready: currently aliases db.liveConnected.

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

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