HWLAB DEV Runtime Boundary

This reference defines the stable DEV environment, port, k3s, and runtime substitution rules.

Public DEV Ports

Surface	URL
Cloud Web browser entry	`http://74.48.78.17:16666/`
API/edge entry	`http://74.48.78.17:16667/`
API/live health	`http://74.48.78.17:16667/health/live`

Public :6666 and :6667 are deprecated as browser/API acceptance targets. Internal k3s services may still listen on 6667; do not rewrite that as a public endpoint.

Route Shape

The public route is:

master hwlab-frps-dev :16666/:16667
-> D601 hwlab-frpc in namespace hwlab-dev
-> hwlab-cloud-web on internal :8080 for browser traffic
-> hwlab-edge-proxy / hwlab-cloud-api on internal :6667 for API and health

deploy/deploy.json is the source for public endpoint and FRP mapping drift checks. Use:

node scripts/deploy-contract-plan.mjs --check

D601 k3s Source Of Truth

D601 native k3s is the DEV runtime source of truth. Commands that observe or roll a DEV workload must specify:

KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-dev get deploy,svc,pod -o wide

Do not trust the default kubectl context as a DEV runtime signal. On D601 it may point at another cluster such as docker-desktop.

Use the read-only preflight when a runner needs to report k3s visibility:

node scripts/d601-k3s-readonly-observability.mjs

The preflight must not print secret values, kubeconfig material, ConfigMap values, or token content.

Cloud API DB DNS Contract

hwlab-cloud-api reads the DEV database connection string from Secret reference hwlab-cloud-api-dev-db/database-url. The Secret value is not stored in source, not printed by reports, and not required for offline validation.

The non-secret DNS contract is source-controlled:

Field	Value
Service	`cloud-api-db`
Namespace	`hwlab-dev`
Host	`cloud-api-db.hwlab-dev.svc.cluster.local`
Port	`5432`
Port name	`postgres`

deploy/k8s/base/services.yaml must include a selectorless Service/cloud-api-db with that port so k3s DNS has a stable handle before the actual DB endpoints are provisioned. A selectorless Service proves only that the name can exist in cluster DNS; it does not prove a DB endpoint, credential, TCP connection, schema migration, durable persistence, or M4/M5 readiness.

deploy/deploy.json, deploy/k8s/base/workloads.yaml, and internal/cloud/db-contract.mjs must agree on HWLAB_CLOUD_DB_SERVICE_NAME, HWLAB_CLOUD_DB_SERVICE_NAMESPACE, HWLAB_CLOUD_DB_HOST, and HWLAB_CLOUD_DB_PORT. npm run validate checks this agreement offline. A live pass still requires /health/live to report db.ready=true, db.connected=true, and liveDbEvidence=true with secret values redacted.

Durable Runtime Readiness Contract

DB live readiness and durable runtime readiness are separate gates. A /health/live payload with db.connected=true and db.liveDbEvidence=true only proves that the Cloud API reached the DEV DB endpoint without exposing secret values. It does not prove that runtime writes are persisted through a durable store.

When health reports:

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

the Cloud API is using the process-local runtime store in internal/db/runtime-store.mjs. Gateway sessions, box resources, operations, audit events, and evidence records accepted through the runtime can be lost on pod restart, redeploy, or scale-out, and cannot be treated as durable M3/M4/M5 evidence. Users may see accepted operations or evidence disappear after a runtime replacement, and agent-loop/MVP acceptance must remain degraded or blocked even if the DB connection layer is green.

Readiness reports must keep these dimensions distinct:

Dimension	Green condition	Degraded/blocking condition
DB live	`db.ready=true`, `db.connected=true`, `db.liveDbEvidence=true`	Missing env, failed connection, disabled probe, or no `liveDbEvidence`
Runtime durability	`runtime.durable=true` with a durable adapter	`runtime.adapter="memory"` or `runtime.durable=false`

Do not declare DEV-LIVE complete while runtime.adapter="memory" or runtime.durable=false, even when DB live readiness is connected. The next fix boundary is a durable runtime store and migration path; documenting or testing this contract must not mutate runtime state or PROD.

Runtime Substitution Ban

UniDesk services, provider-gateway, backend-core, microservice proxies, local fixtures, and runner-local mocks may support scheduling, CI, CD, source checks, or dry-runs. They cannot be described as HWLAB runtime and cannot satisfy M3, M4, or M5 live evidence.

Stable Sources

deploy/frp/README.md: FRP DEV contract.
docs/d601-k3s-readonly-observability.md: read-only k3s visibility command.
docs/dev-acceptance-matrix.md: DEV endpoint and health acceptance.
pikasTech/HWLAB#61: manual rollout review and automation requirements.

5.1 KiB Raw Blame History