pikasTech-HWLAB/docs/dev-gate-preflight.md

HWLAB DEV Gate Preflight

This preflight is the read-only gate before a real DEV deploy or DEV smoke on D601. It decides whether the current origin/main can enter the real hwlab-dev runtime path, or whether it is blocked by missing contract, artifact, cluster, registry, edge, or safety evidence.

It does not authorize PROD, restart runtime services, read secrets or tokens, substitute UniDesk services for HWLAB runtime, or run heavyweight/browser e2e.

Command

Run from the repository root:

node --check scripts/dev-gate-preflight.mjs
node --check scripts/src/dev-gate-preflight.mjs
node --check scripts/src/registry-capabilities.mjs
node --check scripts/deploy-desired-state-plan.mjs
node --check scripts/src/deploy-desired-state-plan.mjs
node --check scripts/dev-runtime-migration.mjs
node --check scripts/src/dev-runtime-migration.mjs
node --check scripts/refresh-artifact-catalog.mjs
node scripts/deploy-desired-state-plan.mjs --target-ref origin/main --check
node scripts/dev-runtime-migration.mjs --check
node scripts/dev-gate-preflight.mjs

The command writes /tmp/hwlab-dev-gate/dev-preflight-report.json and prints a short JSON summary. A blocked conclusion means the preflight ran correctly but found blockers; the command exits zero by default so the report can be committed as evidence. Use --fail-on-blocked only in CI jobs that should fail on an open gate.

Useful options:

node scripts/dev-gate-preflight.mjs --target-ref origin/main
node scripts/dev-gate-preflight.mjs --report /tmp/hwlab-dev-gate/dev-preflight-report.json
node scripts/dev-gate-preflight.mjs --timeout-ms 5000
node scripts/dev-gate-preflight.mjs --no-write

Read-Only Scope

The preflight checks:

• deploy/deploy.json and deploy/artifact-catalog.dev.json are internally consistent and DEV-only.
• scripts/deploy-desired-state-plan.mjs --target-ref origin/main --check can be run as a read-only source support check for deploy commit/image/tag/workload and env mirror convergence. It does not contact a registry or prove DEV runtime state.
• The deploy manifest, artifact catalog, catalog service commits, and image tags are covered by the selected origin/main target. If origin/main is a report-only evidence commit whose changes do not touch artifact build inputs, the preflight may accept the artifact source recorded in /tmp/hwlab-dev-gate/dev-artifacts.json.
• The artifact catalog clearly separates source commit, artifact commit, ciPublished, registryVerified, and per-service digest state.
• The artifact catalog has real publish and registry digest evidence, or stays blocked with not_published digests.
• /tmp/hwlab-dev-gate/dev-artifacts.json, when present, proves all frozen DEV service artifacts were published for the selected target or for an artifact source commit that still covers the target.
• Registry capability evidence is split into process-http-access, docker-daemon-push-access, and k3s-pull-access instead of one ambiguous "registry reachable" result.
• deploy/k8s/base and deploy/k8s/dev parse and remain scoped to hwlab-dev.
• hwlab-cloud-api declares the DEV DB env contract: HWLAB_CLOUD_DB_URL from Secret reference hwlab-cloud-api-dev-db/database-url and HWLAB_CLOUD_DB_SSL_MODE=disable. Runtime readiness dials the redacted host parsed from that Secret URL. cloud-api-db is an optional desired alias only until this repo owns Service plus Endpoint or EndpointSlice manifests and rollout/apply contract.
• scripts/dev-runtime-migration.mjs --check validates the runtime migration source and ledger contract without live DB access. Live read verification and migration apply are separate DEV-only modes requiring explicit flags; default preflight does not read DB secrets or write the DB.
• The local cloud-api health payload reports DB env presence/missing status with redacted values only. This is a readiness gate, not live DB evidence.
• deploy/frp and deploy/master-edge describe the D601-to-master DEV route on public frontend :16666 and API/edge/live :16667. Legacy public :6666/:6667 observations are historical/deprecated only and must not be used as current green evidence or current active blockers.
• The runner can perform read-only KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl probes against hwlab-dev and verify node d601; default docker-desktop kubeconfig output is not DEV evidence.
• /tmp/hwlab-dev-gate/dev-edge-health.json, when present, records read-only public edge, frps, tunnel-health, and k3s observability evidence.
• http://74.48.78.17:16667/health/live responds.
• Catalog image manifests are visible without reading credentials. A failed manifest read is tracked as a #66 registry reachability dimension and must not be conflated with missing publish digests.
• Catalog images do not point at UniDesk, provider-gateway, or microservice-proxy substitutes; deploy/deploy.json must not contain generated image identity.

Registry Capability Dimensions

registryCapabilities appears in both the preflight report and the artifact publish report. The dimensions are:

• process-http-access: runner/BuildKit-side HTTP access to /v2/. This is the publish-path registry API preflight for the current BuildKit-based G14 pipeline.
• docker-daemon-push-access: read-only Docker daemon evidence for the local/internal registry target. This is a legacy diagnostic only; it is not a publish-path capability and must not block BuildKit publish readiness.
• k3s-pull-access: read-only native-k3s kubectl evidence for whether the DEV cluster can inspect image pull state. This is the deploy-path capability.

Verdict Rules

ready requires all checks to pass and no open blocker.

degraded means a non-required capability is observable but incomplete, such as legacy Docker daemon registry visibility being unavailable after the G14 publish path has moved to BuildKit. blocked is expected until the required real DEV runtime path can be proven. Each blocker includes a type, scope, summary, and nextTask so the next task is the smallest repair needed before rerunning the preflight.

The DB gate has two common blocked scopes:

• cloud-api-db-env-contract: manifest/Kubernetes placeholders are incomplete. The optional cloud-api-db alias is not part of this readiness gate.
• cloud-api-db-health-gate: runtime env presence is missing. The next task is to configure the DEV Secret/env names, not to print or commit any secret value.

For catalog commit mismatch, the preflight emits an artifactIdentity.refreshCommands.blocked command. Use it when the source commit changed but publish is still blocked:

node scripts/deploy-desired-state-plan.mjs --target-ref origin/main --pretty
node scripts/refresh-artifact-catalog.mjs --target-ref origin/main --blocked --no-write

Only use the published refresh path after /tmp/hwlab-dev-gate/dev-artifacts.json proves every frozen service has a registry digest for that same source commit:

node scripts/deploy-desired-state-plan.mjs --target-ref origin/main --pretty
node scripts/refresh-artifact-catalog.mjs --target-ref origin/main --publish-report /tmp/hwlab-dev-gate/dev-artifacts.json --no-write

Committed DEV artifact reports can prove required service digests only for the source commit they name. If the selected origin/main target drifts onto files that change artifact build inputs, the preflight can still reopen artifact-source-commit or dev-artifact-publish even though the base-image blocker stays closed. Remaining registry manifest-read failures are #66 reachability evidence, not a reason to reopen the base-image blocker.

This is M3 virtual hardware trusted-loop support only. It does not claim M3 DEV-LIVE unless a real DO1 -> patch-panel -> DI1 chain is observed through the current DEV endpoint.