docs: add M0 contract audit

protocol/examples/m0-contract/audit-event.json

@@ -0,0 +1,22 @@
+{
+  "auditId": "aud_01J00000000000000000000010",
+  "traceId": "trc_01J00000000000000000000010",
+  "actorType": "worker",
+  "actorId": "wrk_01J00000000000000000000010",
+  "action": "hardware.operation.succeeded",
+  "targetType": "hardware_operation",
+  "targetId": "op_01J00000000000000000000010",
+  "projectId": "prj_01J00000000000000000000010",
+  "gatewaySessionId": "gws_01J00000000000000000000010",
+  "workerSessionId": "wks_01J00000000000000000000010",
+  "operationId": "op_01J00000000000000000000010",
+  "serviceId": "hwlab-agent-worker",
+  "environment": "dev",
+  "outcome": "succeeded",
+  "reason": "operation_completed",
+  "metadata": {
+    "capabilityId": "cap_01J00000000000000000000010",
+    "evidenceId": "evd_01J00000000000000000000010"
+  },
+  "occurredAt": "2026-05-21T00:00:05.000Z"
+}

protocol/examples/m0-contract/capability-topology.json

@@ -0,0 +1,224 @@
+{
+  "contract": "m0-capability-topology",
+  "project": {
+    "projectId": "prj_01J00000000000000000000010",
+    "name": "M0 Contract Project",
+    "status": "active",
+    "environment": "dev",
+    "createdBy": "usr_01J00000000000000000000010",
+    "createdAt": "2026-05-21T00:00:00.000Z",
+    "updatedAt": "2026-05-21T00:00:00.000Z"
+  },
+  "gatewaySession": {
+    "gatewaySessionId": "gws_01J00000000000000000000010",
+    "projectId": "prj_01J00000000000000000000010",
+    "serviceId": "hwlab-gateway-simu",
+    "gatewayId": "gtw_01J00000000000000000000010",
+    "endpoint": "http://127.0.0.1:7101",
+    "status": "connected",
+    "environment": "dev",
+    "startedAt": "2026-05-21T00:00:00.000Z",
+    "lastSeenAt": "2026-05-21T00:00:02.000Z",
+    "labels": {
+      "mode": "simulated"
+    }
+  },
+  "resources": [
+    {
+      "resourceId": "res_01J00000000000000000000010",
+      "projectId": "prj_01J00000000000000000000010",
+      "gatewaySessionId": "gws_01J00000000000000000000010",
+      "boxId": "box_01J00000000000000000000010",
+      "resourceType": "power_supply",
+      "name": "simulated power supply",
+      "state": "available",
+      "environment": "dev",
+      "metadata": {
+        "ports": ["out0"]
+      },
+      "createdAt": "2026-05-21T00:00:00.000Z",
+      "updatedAt": "2026-05-21T00:00:00.000Z"
+    },
+    {
+      "resourceId": "res_01J00000000000000000000011",
+      "projectId": "prj_01J00000000000000000000010",
+      "gatewaySessionId": "gws_01J00000000000000000000010",
+      "boxId": "box_01J00000000000000000000010",
+      "resourceType": "board",
+      "name": "simulated dut board",
+      "state": "reserved",
+      "environment": "dev",
+      "metadata": {
+        "ports": ["vin", "uart0"]
+      },
+      "createdAt": "2026-05-21T00:00:00.000Z",
+      "updatedAt": "2026-05-21T00:00:00.000Z"
+    }
+  ],
+  "capabilities": [
+    {
+      "capabilityId": "cap_01J00000000000000000000010",
+      "resourceId": "res_01J00000000000000000000010",
+      "projectId": "prj_01J00000000000000000000010",
+      "name": "power.cycle",
+      "description": "Cycle simulated DUT power through the gateway.",
+      "direction": "bidirectional",
+      "valueType": "object",
+      "constraints": {
+        "holdMs": {
+          "minimum": 100,
+          "maximum": 5000
+        }
+      },
+      "mutatesState": true,
+      "createdAt": "2026-05-21T00:00:00.000Z",
+      "updatedAt": "2026-05-21T00:00:00.000Z"
+    },
+    {
+      "capabilityId": "cap_01J00000000000000000000011",
+      "resourceId": "res_01J00000000000000000000010",
+      "projectId": "prj_01J00000000000000000000010",
+      "name": "power.set_voltage",
+      "description": "Set simulated output voltage.",
+      "direction": "input",
+      "valueType": "number",
+      "unit": "V",
+      "constraints": {
+        "minimum": 0,
+        "maximum": 12
+      },
+      "mutatesState": true,
+      "createdAt": "2026-05-21T00:00:00.000Z",
+      "updatedAt": "2026-05-21T00:00:00.000Z"
+    }
+  ],
+  "wiringConfig": {
+    "wiringConfigId": "wir_01J00000000000000000000010",
+    "projectId": "prj_01J00000000000000000000010",
+    "gatewaySessionId": "gws_01J00000000000000000000010",
+    "name": "M0 simulated DUT power wiring",
+    "status": "active",
+    "connections": [
+      {
+        "from": {
+          "resourceId": "res_01J00000000000000000000010",
+          "port": "out0",
+          "capabilityId": "cap_01J00000000000000000000011"
+        },
+        "to": {
+          "resourceId": "res_01J00000000000000000000011",
+          "port": "vin"
+        },
+        "mode": "exclusive"
+      }
+    ],
+    "constraints": {
+      "oneActiveConfigPerResourceGroup": true,
+      "cyclesAllowed": false
+    },
+    "createdAt": "2026-05-21T00:00:00.000Z",
+    "updatedAt": "2026-05-21T00:00:00.000Z"
+  },
+  "patchPanelStatus": {
+    "patchPanelStatusId": "pps_01J00000000000000000000010",
+    "projectId": "prj_01J00000000000000000000010",
+    "gatewaySessionId": "gws_01J00000000000000000000010",
+    "wiringConfigId": "wir_01J00000000000000000000010",
+    "serviceId": "hwlab-patch-panel",
+    "state": "active",
+    "environment": "dev",
+    "activeConnections": [
+      {
+        "fromResourceId": "res_01J00000000000000000000010",
+        "fromPort": "out0",
+        "toResourceId": "res_01J00000000000000000000011",
+        "toPort": "vin"
+      }
+    ],
+    "observedAt": "2026-05-21T00:00:01.000Z",
+    "metadata": {
+      "connectionCount": 1
+    }
+  },
+  "agentSession": {
+    "agentSessionId": "ags_01J00000000000000000000010",
+    "projectId": "prj_01J00000000000000000000010",
+    "serviceId": "hwlab-agent-mgr",
+    "status": "active",
+    "environment": "dev",
+    "requestedBy": "usr_01J00000000000000000000010",
+    "goal": "Cycle DUT power and persist evidence.",
+    "startedAt": "2026-05-21T00:00:02.000Z",
+    "updatedAt": "2026-05-21T00:00:02.000Z"
+  },
+  "workerSession": {
+    "workerSessionId": "wks_01J00000000000000000000010",
+    "agentSessionId": "ags_01J00000000000000000000010",
+    "projectId": "prj_01J00000000000000000000010",
+    "serviceId": "hwlab-agent-worker",
+    "gatewaySessionId": "gws_01J00000000000000000000010",
+    "status": "active",
+    "environment": "dev",
+    "startedAt": "2026-05-21T00:00:03.000Z",
+    "updatedAt": "2026-05-21T00:00:03.000Z"
+  },
+  "hardwareOperation": {
+    "operationId": "op_01J00000000000000000000010",
+    "projectId": "prj_01J00000000000000000000010",
+    "gatewaySessionId": "gws_01J00000000000000000000010",
+    "agentSessionId": "ags_01J00000000000000000000010",
+    "workerSessionId": "wks_01J00000000000000000000010",
+    "resourceId": "res_01J00000000000000000000010",
+    "capabilityId": "cap_01J00000000000000000000010",
+    "requestedBy": "usr_01J00000000000000000000010",
+    "input": {
+      "cycle": true,
+      "holdMs": 250
+    },
+    "output": {
+      "powerState": "on"
+    },
+    "status": "succeeded",
+    "environment": "dev",
+    "requestedAt": "2026-05-21T00:00:03.000Z",
+    "startedAt": "2026-05-21T00:00:04.000Z",
+    "completedAt": "2026-05-21T00:00:05.000Z",
+    "updatedAt": "2026-05-21T00:00:05.000Z"
+  },
+  "traceEvents": [
+    {
+      "traceEventId": "tev_01J00000000000000000000010",
+      "traceId": "trc_01J00000000000000000000010",
+      "projectId": "prj_01J00000000000000000000010",
+      "agentSessionId": "ags_01J00000000000000000000010",
+      "workerSessionId": "wks_01J00000000000000000000010",
+      "operationId": "op_01J00000000000000000000010",
+      "serviceId": "hwlab-agent-worker",
+      "level": "info",
+      "message": "hardware operation completed",
+      "environment": "dev",
+      "metadata": {
+        "status": "succeeded"
+      },
+      "occurredAt": "2026-05-21T00:00:05.000Z"
+    }
+  ],
+  "evidenceRecord": {
+    "evidenceId": "evd_01J00000000000000000000010",
+    "projectId": "prj_01J00000000000000000000010",
+    "operationId": "op_01J00000000000000000000010",
+    "agentSessionId": "ags_01J00000000000000000000010",
+    "workerSessionId": "wks_01J00000000000000000000010",
+    "kind": "report",
+    "uri": "protocol/examples/m0-contract/evidence/power-cycle-report.md",
+    "mimeType": "text/markdown",
+    "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+    "sizeBytes": 0,
+    "serviceId": "hwlab-agent-worker",
+    "environment": "dev",
+    "metadata": {
+      "source": "m0_contract_example"
+    },
+    "createdAt": "2026-05-21T00:00:05.000Z"
+  }
+}

protocol/examples/m0-contract/deploy-manifest.dev.json

@@ -0,0 +1,126 @@
+{
+  "manifestVersion": "v1",
+  "environment": "dev",
+  "commitId": "6509a35804ee97dd8d711bdde334c46ca37c55b9",
+  "namespace": "hwlab-dev",
+  "endpoint": "http://74.48.78.17:6667",
+  "profiles": {
+    "dev": {
+      "name": "dev",
+      "enabled": true,
+      "namespace": "hwlab-dev",
+      "endpoint": "http://74.48.78.17:6667",
+      "notes": "M0 contract example only; not a deploy manifest."
+    }
+  },
+  "services": [
+    {
+      "serviceId": "hwlab-cloud-api",
+      "image": "ghcr.io/pikastech/hwlab-cloud-api:6509a35",
+      "namespace": "hwlab-dev",
+      "healthPath": "/healthz",
+      "profile": "dev",
+      "replicas": 1,
+      "env": {
+        "HWLAB_ENV": "dev"
+      }
+    },
+    {
+      "serviceId": "hwlab-cloud-web",
+      "image": "ghcr.io/pikastech/hwlab-cloud-web:6509a35",
+      "namespace": "hwlab-dev",
+      "healthPath": "/healthz",
+      "profile": "dev",
+      "replicas": 1
+    },
+    {
+      "serviceId": "hwlab-agent-mgr",
+      "image": "ghcr.io/pikastech/hwlab-agent-mgr:6509a35",
+      "namespace": "hwlab-dev",
+      "healthPath": "/healthz",
+      "profile": "dev",
+      "replicas": 1
+    },
+    {
+      "serviceId": "hwlab-agent-worker",
+      "image": "ghcr.io/pikastech/hwlab-agent-worker:6509a35",
+      "namespace": "hwlab-dev",
+      "healthPath": "/healthz",
+      "profile": "dev",
+      "replicas": 1
+    },
+    {
+      "serviceId": "hwlab-gateway",
+      "image": "ghcr.io/pikastech/hwlab-gateway:6509a35",
+      "namespace": "hwlab-dev",
+      "healthPath": "/healthz",
+      "profile": "dev",
+      "replicas": 0
+    },
+    {
+      "serviceId": "hwlab-gateway-simu",
+      "image": "ghcr.io/pikastech/hwlab-gateway-simu:6509a35",
+      "namespace": "hwlab-dev",
+      "healthPath": "/healthz",
+      "profile": "dev",
+      "replicas": 1
+    },
+    {
+      "serviceId": "hwlab-box-simu",
+      "image": "ghcr.io/pikastech/hwlab-box-simu:6509a35",
+      "namespace": "hwlab-dev",
+      "healthPath": "/healthz",
+      "profile": "dev",
+      "replicas": 1
+    },
+    {
+      "serviceId": "hwlab-patch-panel",
+      "image": "ghcr.io/pikastech/hwlab-patch-panel:6509a35",
+      "namespace": "hwlab-dev",
+      "healthPath": "/healthz",
+      "profile": "dev",
+      "replicas": 1
+    },
+    {
+      "serviceId": "hwlab-router",
+      "image": "ghcr.io/pikastech/hwlab-router:6509a35",
+      "namespace": "hwlab-dev",
+      "healthPath": "/healthz",
+      "profile": "dev",
+      "replicas": 1
+    },
+    {
+      "serviceId": "hwlab-tunnel-client",
+      "image": "ghcr.io/pikastech/hwlab-tunnel-client:6509a35",
+      "namespace": "hwlab-dev",
+      "healthPath": "/healthz",
+      "profile": "dev",
+      "replicas": 1
+    },
+    {
+      "serviceId": "hwlab-edge-proxy",
+      "image": "ghcr.io/pikastech/hwlab-edge-proxy:6509a35",
+      "namespace": "hwlab-dev",
+      "healthPath": "/healthz",
+      "profile": "dev",
+      "replicas": 1
+    },
+    {
+      "serviceId": "hwlab-cli",
+      "image": "ghcr.io/pikastech/hwlab-cli:6509a35",
+      "namespace": "hwlab-dev",
+      "healthPath": "/healthz",
+      "profile": "dev",
+      "replicas": 0
+    },
+    {
+      "serviceId": "hwlab-agent-skills",
+      "image": "ghcr.io/pikastech/hwlab-agent-skills:6509a35",
+      "namespace": "hwlab-dev",
+      "healthPath": "/healthz",
+      "profile": "dev",
+      "replicas": 0
+    }
+  ],
+  "createdAt": "2026-05-21T00:00:00.000Z"
+}

protocol/examples/m0-contract/json-rpc-error.json

@@ -0,0 +1,20 @@
+{
+  "jsonrpc": "2.0",
+  "id": "req_01J00000000000000000000010",
+  "error": {
+    "code": -32020,
+    "message": "Requested hardware capability is unavailable",
+    "data": {
+      "projectId": "prj_01J00000000000000000000010",
+      "gatewaySessionId": "gws_01J00000000000000000000010",
+      "resourceId": "res_01J00000000000000000000010",
+      "capabilityId": "cap_01J00000000000000000000010",
+      "reason": "capability_unavailable"
+    }
+  },
+  "meta": {
+    "traceId": "trc_01J00000000000000000000010",
+    "serviceId": "hwlab-gateway",
+    "environment": "dev"
+  }
+}

protocol/examples/m0-contract/json-rpc-request.json

@@ -0,0 +1,26 @@
+{
+  "jsonrpc": "2.0",
+  "id": "req_01J00000000000000000000010",
+  "method": "hardware.operation.request",
+  "params": {
+    "projectId": "prj_01J00000000000000000000010",
+    "gatewaySessionId": "gws_01J00000000000000000000010",
+    "resourceId": "res_01J00000000000000000000010",
+    "capabilityId": "cap_01J00000000000000000000010",
+    "input": {
+      "cycle": true,
+      "holdMs": 250
+    },
+    "audit": {
+      "actorType": "user",
+      "actorId": "usr_01J00000000000000000000010",
+      "reason": "m0_contract_example"
+    }
+  },
+  "meta": {
+    "traceId": "trc_01J00000000000000000000010",
+    "actorId": "usr_01J00000000000000000000010",
+    "serviceId": "hwlab-cloud-api",
+    "environment": "dev"
+  }
+}

protocol/examples/m0-contract/json-rpc-response.json

@@ -0,0 +1,14 @@
+{
+  "jsonrpc": "2.0",
+  "id": "req_01J00000000000000000000010",
+  "result": {
+    "accepted": true,
+    "operationId": "op_01J00000000000000000000010",
+    "status": "accepted"
+  },
+  "meta": {
+    "traceId": "trc_01J00000000000000000000010",
+    "serviceId": "hwlab-agent-mgr",
+    "environment": "dev"
+  }
+}

protocol/examples/m0-contract/service-ids.json

@@ -0,0 +1,19 @@
+{
+  "contract": "m0-service-ids",
+  "environment": "dev",
+  "serviceIds": [
+    "hwlab-cloud-api",
+    "hwlab-cloud-web",
+    "hwlab-agent-mgr",
+    "hwlab-agent-worker",
+    "hwlab-gateway",
+    "hwlab-gateway-simu",
+    "hwlab-box-simu",
+    "hwlab-patch-panel",
+    "hwlab-router",
+    "hwlab-tunnel-client",
+    "hwlab-edge-proxy",
+    "hwlab-cli",
+    "hwlab-agent-skills"
+  ]
+}