diff --git a/docs/dev-acceptance-checklist.json b/docs/dev-acceptance-checklist.json index 0a74d6bf..f262b100 100644 --- a/docs/dev-acceptance-checklist.json +++ b/docs/dev-acceptance-checklist.json @@ -5,6 +5,25 @@ "issue": "pikasTech/HWLAB#22", "environment": "dev", "endpoint": "http://74.48.78.17:16667", + "publicEndpoints": { + "frontend": "http://74.48.78.17:16666", + "api": "http://74.48.78.17:16667", + "edge": "http://74.48.78.17:16667" + }, + "internalServicePorts": [ + { + "serviceId": "hwlab-cloud-api", + "scope": "k3s-service", + "port": 6667, + "note": "Internal k3s service port only; not a public DEV endpoint." + }, + { + "serviceId": "hwlab-edge-proxy", + "scope": "k3s-service", + "port": 6667, + "note": "Internal k3s service/listen port only; public API/edge ingress is 16667." + } + ], "runtimeSubstitutePolicy": { "allowedExternalRoles": [ "scheduling", @@ -17,6 +36,40 @@ "unidesk-microservice-proxy" ] }, + "m3EvidenceClassification": { + "p0Scope": "M3 virtual hardware trusted loop", + "requiredCardinality": { + "hwlab-box-simu": 2, + "hwlab-gateway-simu": 2, + "hwlab-patch-panel": 1 + }, + "m3Live": { + "requiredLink": "DO1 -> hwlab-patch-panel -> DI1", + "requiredIdentifiers": [ + "operationId", + "traceId", + "auditId", + "evidenceId" + ], + "classification": "DEV-LIVE" + }, + "m3Support": [ + "endpoint-freeze", + "read-only-edge-curl", + "source-contract", + "static-manifest-cardinality", + "local-smoke", + "dry-run-fixture" + ], + "nonP0": [ + "SOURCE", + "LOCAL", + "DRY-RUN", + "fixture-only", + "edge-only-diagnostic" + ], + "promotionRule": "Do not classify M3 support or non-P0 evidence as DEV-LIVE unless the traced DO1 -> hwlab-patch-panel -> DI1 path is observed." + }, "artifactObservabilityFields": [ "serviceId", "commitId", @@ -37,11 +90,18 @@ }, "route": [ { - "id": "dev-endpoint", - "label": "DEV endpoint", + "id": "dev-api-edge-endpoint", + "label": "DEV API/edge endpoint", "serviceId": "hwlab-edge-proxy", "endpoint": "http://74.48.78.17:16667", - "role": "public-dev-ingress" + "role": "public-api-edge-ingress" + }, + { + "id": "dev-frontend-endpoint", + "label": "DEV frontend endpoint", + "serviceId": "hwlab-cloud-web", + "endpoint": "http://74.48.78.17:16666", + "role": "public-frontend" }, { "id": "master-edge-proxy", @@ -343,8 +403,8 @@ "id": "endpoint-freeze", "order": 2, "probe": "Compare documented and fixture DEV endpoints.", - "successCriteria": "All DEV endpoints equal http://74.48.78.17:16667.", - "failureCriteria": "Any alternate DEV endpoint or PROD target.", + "successCriteria": "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.", + "failureCriteria": "Any alternate public DEV endpoint, old public :6667, or PROD target.", "blockerClass": "environment_blocker" }, { @@ -383,7 +443,7 @@ "id": "cloud-surface", "order": 7, "probe": "Check cloud API health and cloud web endpoint configuration.", - "successCriteria": "Cloud API health is valid and web assets point at the fixed DEV endpoint.", + "successCriteria": "Cloud API health is valid on public :16667; web assets are served on public :16666 and point API traffic at :16667 or the internal k3s API service.", "failureCriteria": "Bad health, endpoint drift, or direct hardware control from web.", "blockerClass": "runtime_blocker" }, @@ -391,8 +451,8 @@ "id": "gateway-sim-patch-panel", "order": 8, "probe": "Check gateway, gateway simulator, box simulator, and patch-panel health/status.", - "successCriteria": "Health/status JSON is parseable and topology keeps routing under patch-panel ownership.", - "failureCriteria": "Missing health, invalid topology, or bypass path.", + "successCriteria": "Health/status JSON is parseable and topology keeps routing under patch-panel ownership; for M3 live, a traced DO1 -> patch-panel -> DI1 operation exists.", + "failureCriteria": "Missing health, invalid topology, bypass path, or any attempt to promote support/fixture evidence to M3 live.", "blockerClass": "runtime_blocker" }, { diff --git a/docs/dev-acceptance-matrix.md b/docs/dev-acceptance-matrix.md index a22cc49c..762e2880 100644 --- a/docs/dev-acceptance-matrix.md +++ b/docs/dev-acceptance-matrix.md @@ -6,15 +6,40 @@ DEV or PROD deployment. ## Fixed Boundary -- DEV endpoint: `http://74.48.78.17:16667` +- DEV frontend endpoint: `http://74.48.78.17:16666` +- DEV API/edge endpoint: `http://74.48.78.17:16667` - Deploy environment: `dev` -- Legacy endpoint `:6666` is deprecated; browser entry is `:16666` and API/health entry is `:16667`. +- 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 a real +`DO1 -> hwlab-patch-panel -> 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 `DO1 -> patch-panel -> DI1` +link. These observations must not be written as `DEV-LIVE`. + ## Required Artifact Observability Every deployable HWLAB artifact that participates in DEV acceptance must expose @@ -42,19 +67,19 @@ provide a current health timestamp. Existing skeleton services may expose | Component | Service ID | Check | Success | Failure | | --- | --- | --- | --- | --- | -| DEV 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 | +| 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` | Static asset check and configured DEV endpoint | Web bundle references `http://74.48.78.17:16667` and does not call hardware directly | Endpoint drift, direct hardware control path, missing asset | +| Cloud Web | `hwlab-cloud-web` | `GET http://74.48.78.17:16666/` plus static asset check and configured API endpoint | Public browser entry serves the web bundle on `:16666`; API calls target `http://74.48.78.17:16667` or the internal k3s API service, and do not call hardware directly | Endpoint drift, public web served from `:6667`, 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 | +| 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 @@ -67,13 +92,13 @@ 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:16667` 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` | +| 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; 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` | +| 7 | Check cloud API/web surface. | Cloud API health is valid on public `:16667`; web assets are served on public `:16666` and point API traffic at `:16667` or the internal k3s API service. | 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; 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` |