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 and redacted Secret refs without exposing 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, health reports db.status: "degraded" and still keeps db.connected: false, db.ready: false, and db.connectionChecked: false; env presence is not live DB evidence.

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