pikasTech-HWLAB/docs/dev-acceptance-matrix.md

HWLAB DEV Acceptance Matrix

This matrix is the DEV acceptance contract for the MVP runtime. It is scoped to static review and lightweight smoke checks only. It does not authorize a real DEV or PROD deployment.

Fixed Boundary

• DEV endpoint: http://74.48.78.17:6667
• Deploy environment: dev
• PROD endpoint :6666 is reserved and must not be targeted by this matrix.
• Runtime route: client, master hwlab-edge-proxy, frp, D601 hwlab-dev/hwlab-router, then HWLAB cloud/runtime services.
• UniDesk backend, provider-gateway, and microservice proxy are not accepted as substitutes for HWLAB runtime services in this first version. They may remain external scheduling, CI, or CD support only.

Required Artifact Observability

Every deployable HWLAB artifact that participates in DEV acceptance must expose or be joined with these fields:

Field	Requirement
serviceId	One of the frozen HWLAB service IDs.
commitId	Git commit that produced the artifact, short or full SHA.
image	Image repository/name when containerized, or package artifact name for non-container artifacts.
tag	Immutable or traceable tag, preferably including the commit.
digest	Content digest when the artifact is an image or build output that supports digests.
buildSource	Source repository, branch/ref, and build workflow or local command.
deployEnv	Must be dev for this matrix.
healthTimestamp	ISO-8601 timestamp from the health observation or smoke collector.

Missing digest is allowed only for non-container client assets or local dry-run artifacts, and must be recorded as not_applicable with a reason.

Health Contract

All health responses must be JSON, include serviceId, identify dev, and provide a current health timestamp. Existing skeleton services may expose observedAt; the acceptance collector maps it to healthTimestamp.

Component	Service ID	Check	Success	Failure
DEV ingress	hwlab-edge-proxy	GET http://74.48.78.17:6667/health or routed service health	HTTP 2xx/3xx reaches HWLAB DEV path and reports edge identity or downstream HWLAB identity	Timeout, non-HWLAB response, PROD route, missing artifact fields
master edge proxy	hwlab-edge-proxy	Edge proxy health and route table observation	Route for http://74.48.78.17:6667 forwards to frp and identifies commit/image	No DEV route, wrong port, missing route observability
frp tunnel	hwlab-tunnel-client	Tunnel session/status observation	Tunnel for DEV route is established to D601 router and identifies commit/image	Tunnel down, wrong target, ambiguous service identity
D601 router	hwlab-router	hwlab-dev/hwlab-router health/status	Router is live, environment is dev, route target is cloud API/web or runtime service	Namespace mismatch, route missing, stale health timestamp
Cloud API	hwlab-cloud-api	GET /health, GET /live, optional JSON-RPC /rpc probe	Returns service ID, dev, healthy/live status, and accepts a harmless protocol probe	HTTP error, unknown service ID, wrong environment, invalid JSON-RPC envelope
Cloud Web	hwlab-cloud-web	Static asset check and configured DEV endpoint	Web bundle references http://74.48.78.17:6667 and does not call hardware directly	Endpoint drift, direct hardware control path, missing asset
Agent manager	hwlab-agent-mgr	Agent scheduling health/status	Reports live manager, commit/image, and DEV environment; no worker leak after smoke	Scheduler unavailable, wrong environment, unbounded worker session
Agent worker	hwlab-agent-worker	Worker health/status during dry-run or scoped smoke	Worker session is scoped to DEV project and emits trace/audit identifiers	Missing session identity, unsafe mutation, cleanup failure
Agent skills	hwlab-agent-skills	Skill bundle version/status	Skill artifact is traceable to commit/build source and compatible with worker	Unversioned skill bundle, missing build source
Gateway	hwlab-gateway	GET /health/live and GET /status when present	Reports DEV gateway boundary and does not bypass patch-panel constraints	Hardware boundary unavailable, non-DEV gateway, direct box mutation
Gateway simulator	hwlab-gateway-simu	GET /health/live, GET /status, GET /boxes	Simulator is live, lists expected box resources, and identifies DEV project	Simulator down, box list missing, stale timestamp
Box simulator	hwlab-box-simu	GET /health/live, GET /status	Simulator is live and reports resources, ports, and patch-panel-only propagation	Cross-device propagation outside patch panel, missing resource state
Patch panel	hwlab-patch-panel	GET /health/live, GET /status, GET /wiring	Wiring config is parseable and patch-panel state owns routing decisions	Invalid topology, direct bypass path, stale patch state
CLI	hwlab-cli	npm run cli:health and dry-run command	CLI uses DEV endpoint and dry-run states no DEV/PROD changes were made	Wrong endpoint, missing dry-run guard, real mutation attempted

DEV Smoke Matrix

The smoke sequence must run in order and stop on the first critical blocker. Network checks may be replaced by recorded observations when the runner cannot reach the DEV host, but replacement evidence must include the artifact fields listed above.

Step	Probe	Success Criteria	Failure Criteria	Blocker Class
1	Confirm repository contract files and JSON checklist parse.	docs/dev-acceptance-matrix.md exists and docs/dev-acceptance-checklist.json parses.	Missing file or invalid JSON.	contract_blocker
2	Verify frozen DEV endpoint.	Endpoint is exactly http://74.48.78.17:6667 in docs/checklist/runtime fixtures.	Any alternate DEV endpoint or PROD target.	environment_blocker
3	Observe DEV ingress health.	Request reaches HWLAB DEV route and returns HWLAB identity or accepted downstream health.	Timeout, non-HWLAB target, wrong port.	network_blocker
4	Observe master edge proxy route.	Edge route maps DEV endpoint to frp and records artifact identity.	Missing route, stale route, missing artifact identity.	network_blocker
5	Observe frp tunnel.	Tunnel links master edge to D601 router for DEV.	Tunnel down or target mismatch.	network_blocker
6	Observe D601 hwlab-dev/hwlab-router.	Router is live and forwards only to HWLAB DEV services.	Namespace mismatch or route bypass.	runtime_blocker
7	Check cloud API/web surface.	Cloud API health is valid; web assets point at fixed DEV endpoint.	Bad health, endpoint drift, direct hardware control from web.	runtime_blocker
8	Check gateway, simulator, box simulator, and patch-panel contracts.	Health/status JSON is parseable and topology keeps routing under patch-panel ownership.	Missing health, invalid topology, bypass path.	runtime_blocker
9	Check agent manager, worker, and skills contracts.	Agent artifacts are traceable; dry-run/scoped smoke emits session, trace, audit, and cleanup evidence.	Missing traceability, unsafe mutation, cleanup leak.	agent_blocker
10	Verify evidence and artifact observability.	Every accepted artifact has service ID, commit, image/tag/digest or reason, build source, env, and health timestamp.	Missing required observability field.	observability_blocker

Pass And Fail Rules

The matrix passes only when every smoke step is either observed as successful or explicitly marked not applicable with a non-production reason. A step is failed when the observed result contradicts a frozen contract, cannot be parsed, or cannot be tied to a traceable HWLAB artifact.

Critical blockers are contract_blocker, environment_blocker, network_blocker, runtime_blocker, agent_blocker, observability_blocker, and safety_blocker. A safety_blocker must be raised for any attempted PROD deployment, real deployment from this matrix, secret read, heavyweight e2e run, or UniDesk runtime substitution.

First Version Exclusions

• No PROD deployment or PROD smoke.
• No real DEV deployment from this document.
• No heavyweight e2e or destructive hardware action.
• No secret or token reads.
• No replacement of HWLAB runtime services by UniDesk backend, provider-gateway, or microservice proxy.