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 frontend endpoint: http://74.48.78.17:16666
• DEV API/edge endpoint: http://74.48.78.17:16667
• Deploy environment: dev
• Legacy public endpoints :6666 and :6667 are deprecated; browser entry is :16666 and API/health entry is :16667.
• Internal k3s service ports may still use 6667, for example hwlab-cloud-api and hwlab-edge-proxy. Internal 6667 is not a public DEV acceptance endpoint.
• 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.

M3 Evidence Classification

Current P0 DEV acceptance remains the M3 virtual hardware trusted loop: two hwlab-box-simu instances, two hwlab-gateway-simu instances, and one hwlab-patch-panel.

M3 live can be claimed only when a DEV observation proves the live res_boxsimu_1:DO1 -> hwlab-patch-panel -> res_boxsimu_2:DI1 path and records the operation, trace, audit, and evidence identifiers. The patch panel must own the route decision; direct box-to-box propagation or fixture output is not M3 live evidence.

M3 support includes this endpoint freeze, read-only public edge curl evidence, source contracts, static manifest cardinality, local smoke output, and dry-run fixtures. These items support release or pre-release decisions, but they are not P0 live acceptance.

Non-P0 includes SOURCE, LOCAL, DRY-RUN, fixture-only, diagnostic, and edge-only observations that do not prove the full res_boxsimu_1 -> hwlab-patch-panel -> res_boxsimu_2 link. These observations must not be written as DEV-LIVE.

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 API/edge ingress	hwlab-edge-proxy	GET http://74.48.78.17:16667/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:16667 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, redacted DB env readiness, and accepts a harmless protocol probe	HTTP error, unknown service ID, wrong environment, invalid JSON-RPC envelope, missing DB env readiness
Cloud Web	hwlab-cloud-web	GET http://74.48.78.17:16666/, static asset check, and the workbench contract in docs/cloud-web-workbench.md	Public browser entry serves the Cloud Workbench on :16666; default page is a VS Code-style workbench with left activity rail/resource tree, center Agent conversation/trace, right hardware/evidence side panel, and bottom command/input area; API/edge status remains on http://74.48.78.17:16667; browser data uses same-origin /v1, read-only /json-rpc, source/gate report, and blocked report with explicit sourceKind labels	Endpoint drift, public web served from :6667, Gate/M3 Diagnostics used as default homepage, direct write/control endpoint text or calls, missing SOURCE/DRY-RUN/DEV-LIVE/BLOCKED labeling, edge-only evidence presented as M3 DEV-LIVE, 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; this is M3 support until paired with the full patch-panel link observation	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; this is M3 support until paired with the full patch-panel link observation	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; M3 live also requires a traced DO1 -> patch-panel -> DI1 operation	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.

Cloud Web workbench smoke is covered by:

• node scripts/dev-cloud-workbench-smoke.mjs --static
• node scripts/dev-cloud-workbench-smoke.mjs --live --url http://74.48.78.17:16666/

The static mode is SOURCE-level contract evidence only and must report devLive=false; it cannot promote SOURCE, LOCAL, DRY-RUN, or fixture evidence to DEV-LIVE. It observes the PR #114 Markdown help surface as ready when web/hwlab-cloud-web/help.md, the vendored marked renderer, and the non-default internal help route are present. The live mode is optional read-only HTTP plus browser DOM observation and must report blocked or skip structure instead of a false green when the browser check is unavailable.

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 endpoints.	Public frontend is exactly http://74.48.78.17:16666; public API/edge is exactly http://74.48.78.17:16667; internal 6667 appears only as a k3s service/listen port.	Any alternate public DEV endpoint, old public :6667, or PROD target.	environment_blocker
3	Observe DEV API/edge ingress health.	Request reaches HWLAB DEV route and returns HWLAB identity or accepted downstream health.	Timeout, non-HWLAB target, wrong public 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 on public :16667; web assets are served on public :16666; Cloud Web default route is the Cloud Workbench defined in docs/cloud-web-workbench.md; diagnostics/status/gate are secondary; data sources are same-origin /v1, read-only /json-rpc, source/gate report, and blocked report; npm run web:m3-readonly or its workbench-aware successor passes.	Bad health, endpoint drift, Gate/M3 Diagnostics used as default homepage, direct hardware write/control surface from web, missing source labels, or edge-only evidence promoted to M3 DEV-LIVE.	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; for M3 live, a traced DO1 -> patch-panel -> DI1 operation exists.	Missing health, invalid topology, bypass path, or any attempt to promote support/fixture evidence to M3 live.	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.

M3 live cannot be inferred from SOURCE, LOCAL, DRY-RUN, edge-only, or front-end-only evidence. If the evidence does not show the operation, trace, audit, and evidence IDs on the res_boxsimu_1 -> hwlab-patch-panel -> res_boxsimu_2 chain, it is not a pass.

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.