chore: establish hwlab l0 contract skeleton

2026-05-21 14:27:53 +00:00
commit 8f3069035f
41 changed files with 1732 additions and 0 deletions
@@ -0,0 +1,70 @@
+# JSON-RPC Envelope
+
+HWLAB command-style APIs use JSON-RPC 2.0 envelopes.
+
+## Request
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "req_01J00000000000000000000000",
+  "method": "hardware.operation.request",
+  "params": {
+    "projectId": "prj_01J00000000000000000000000"
+  },
+  "meta": {
+    "traceId": "trc_01J00000000000000000000000",
+    "actorId": "usr_01J00000000000000000000000",
+    "serviceId": "hwlab-cloud-api",
+    "environment": "dev"
+  }
+}
+```
+
+## Response
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "req_01J00000000000000000000000",
+  "result": {
+    "accepted": true
+  },
+  "meta": {
+    "traceId": "trc_01J00000000000000000000000",
+    "serviceId": "hwlab-agent-mgr",
+    "environment": "dev"
+  }
+}
+```
+
+## Error
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "req_01J00000000000000000000000",
+  "error": {
+    "code": -32020,
+    "message": "Requested hardware capability is unavailable",
+    "data": {
+      "capabilityId": "cap_01J00000000000000000000000"
+    }
+  },
+  "meta": {
+    "traceId": "trc_01J00000000000000000000000",
+    "serviceId": "hwlab-gateway",
+    "environment": "dev"
+  }
+}
+```
+
+## Envelope Rules
+
+- `jsonrpc` is always `2.0`.
+- `id` is required for request/response flows and must be echoed unchanged.
+- `method` names use dotted lower-case namespaces.
+- `params` must be an object when present.
+- A response contains exactly one of `result` or `error`.
+- `meta.traceId` is required for all cross-service calls.
+- `meta.environment` is `dev` for MVP.