@tetherto/mdk-skill 0.0.0 → 0.12.1

package/dist/skills/mdk-worker-plugin/references/contract-authoring.md

@@ -0,0 +1,135 @@
+# Authoring `mdk-contract.json`
+
+Load this when writing or reviewing a Worker contract. The machine-checkable
+shape is [`mdk-contract.schema.json`](../../../../../../backend/core/mdk-worker/mdk-contract.schema.json) (bundled beside this file as
+`references/mdk-contract.schema.json`); validate with
+[`../scripts/validate-contract.mjs`](../scripts/validate-contract.mjs); this file covers the semantics the schema
+can't express. Real contracts to imitate:
+[`packages/cli/templates/worker/mdk-contract.json`](../../../../../cli/templates/worker/mdk-contract.json) (minimal scaffold / skill
+template), [`backend/workers/miners/avalon/plugin/mdk-contract.json`](../../../../../../backend/workers/miners/avalon/plugin/mdk-contract.json)
+(full-featured; older `plugin/` layout),
+[`backend/workers/temperature/seneca/plugin/mdk-contract.json`](../../../../../../backend/workers/temperature/seneca/plugin/mdk-contract.json) (read-only
+sensor; older `plugin/` layout).
+
+The contract is dual-purpose: the Kernel validates commands against it, and AI
+operator agents read it as context. Every prose field you write is
+simultaneously documentation and agent instructions.
+
+## `metadata`
+
+All five fields required:
+
+```json
+"metadata": {
+  "provider": "microbt",            // vendor slug, lowercase
+  "deviceFamily": "miner",          // miner | power-meter | sensor | container | minerpool
+  "brand": "Whatsminer",            // human-readable
+  "modelsSupported": ["M53S", "M56S"],
+  "overview": "…"                   // what the worker controls + critical environmental constraints
+}
+```
+
+`overview` is the agent's first impression — state what the device is, which
+protocol the Worker wraps, and any site-level caution (e.g. hydro miners must
+not run without coolant flow).
+
+## `capabilities.telemetry`
+
+One entry per channel:
+
+```json
+{ "name": "temperature", "unit": "C", "type": "number",
+  "handler": "src/telemetry/temperature.js",
+  "description": "Hash board temperature. If 0, device is booting." }
+```
+
+- `name` is the wire name — consumers pull it via
+  `telemetry.pull { query: { type: 'metrics' } }` (all channels) or
+  `{ query: { type: 'temperature' } }` (just this one). `Snake_case` by
+  convention (`hashrate_rt`, `power_mode`).
+- `type` is one of `number | string | boolean | array | object` and is what
+  the handler must return (the smoke harness asserts this).
+- Channels that take params (e.g. a `history` channel with `{ limit }`)
+  document them in `description` — extra `query` fields are passed to the
+  handler as `params`.
+- `unit` whenever numeric (`TH/s`, `W`, `C`, `V`, `kW`).
+- `description` must carry semantic boundaries an agent can reason over:
+  sentinel values, staleness, validity ranges.
+
+## `capabilities.commands`
+
+```json
+{ "name": "setPowerPct",
+  "description": "Set power percentage.",
+  "constraints": "Do not call more than once per 5 minutes.",
+  "handler": "src/commands/set-power-pct.js",
+  "params": [ { "name": "pct", "type": "number", "min": 0, "max": 200 } ] }
+```
+
+- `name` is camelCase by convention (`reboot`, `setPowerMode`, `setupPools`).
+- **Bounds rule:** every `number` param declares `min` and `max`. The Kernel's
+  dispatcher rejects out-of-range values with `ERR_PARAM_RANGE` *only for
+  declared bounds*
+  ([`backend/core/kernel/lib/modules/command-dispatcher/index.js`](../../../../../../backend/core/kernel/lib/modules/command-dispatcher/index.js)); nothing
+  else protects the hardware from `setLiquidSupplyTemperature(9000)`. The
+  bundled validator treats a missing bound as an error.
+- `constraints` is a strict semantic limit in prose — rate limits, approval
+  requirements ("Requires two approvals."), ordering rules. Agents obey it;
+  reviewers check it.
+- `examples` (optional) — `{ intent, steps[] }` workflows teaching an agent
+  the optimal use of a non-obvious command.
+- Params arrive at your handler as a named object (`params.pct`). Positional
+  legacy payloads (`{ value }` / `{ args: [] }`) are normalized onto declared
+  names by the runtime — another reason to declare params accurately.
+- Read-only devices: `"commands": []` (see the ABB / Seneca contracts).
+
+## `capabilities.health`
+
+```json
+"health": {
+  "supportedStates": ["OK", "OFFLINE"],
+  "alerts": ["overheat", "fan_failure"],
+  "troubleshooting": ["If temperature > 85 for 5m, reduce power mode before rebooting."]
+}
+```
+
+`supportedStates` is required. `alerts` and `troubleshooting` are optional but
+production contracts declare them — `troubleshooting` is an if-then
+remediation list for agents.
+
+## `capabilities.errors`
+
+Every `ERR_*` code your handlers or device client can throw, mapped to a
+human/AI-readable explanation:
+
+```json
+"errors": {
+  "ERR_BAD_POWER_MODE": "The firmware rejected the requested power mode.",
+  "ERR_DEVICE_CALL_FAILED": "The device API call failed or returned an error."
+}
+```
+
+Errors thrown by handlers travel verbatim in `command.result`/telemetry
+payloads — keeping this map complete is what makes them actionable downstream.
+
+## What does NOT go in the contract
+
+- **No device list.** Devices are supplied at runtime
+  (`WorkerRuntime opts.devices`); the schema rejects a top-level `devices` key.
+- **No secrets** (credentials live in per-device `config`).
+- **No handler implementation detail** — `handler` paths are stripped before
+  the contract leaves the process.
+
+## Validation
+
+```bash
+node ../scripts/validate-contract.mjs <worker>/mdk-contract.json
+```
+
+Checks schema conformance, handler file existence (relative to the contract's
+directory), duplicate telemetry/command names, and the numeric-bounds rule.
+Exit 0 = clean. Pass `--schema-only` to skip the semantic checks and test shape
+alone. The bundled schema is a verbatim copy of the runtime's
+[`backend/core/mdk-worker/mdk-contract.schema.json`](../../../../../../backend/core/mdk-worker/mdk-contract.schema.json); the repo-wide catalogue
+([`backend/workers/scripts/generate-catalogue.js`](../../../../../../backend/workers/scripts/generate-catalogue.js)) lints shipped
+contracts against that same file.

package/dist/skills/mdk-worker-plugin/references/device-families.md

@@ -0,0 +1,96 @@
+# Device families — what exists, what to copy
+
+**Load this only when the user explicitly asks to follow the existing MDK
+Worker families and their structure** — typically when contributing a Worker
+into the MDK monorepo itself, or deliberately mirroring how a shipped family
+handles its device protocol. The families below are tightly coupled to the
+mining use cases they were built for; a third party integrating their own
+device should NOT start from them — the default starting point is
+`../assets/worker-template/` (step 1 of the skill workflow).
+
+All paths under [`backend/workers/`](../../../../../../backend/workers/README.md). Every family below is a
+Worker Plugin on the older module-exporting shape (`plugin/index.js` →
+`{ contract, dir, connect, disconnect? }`); production families additionally
+ship `plugin/boot.js`, which wires Worker-infra services and exposes a
+`start<Family>Worker()` helper. This reflects what's actually shipped today,
+not a recommendation — a **new** Worker should follow the directory-loaded
+`WorkerRuntimeV2` model instead (`mdk-contract.json` + `src/` handlers, no
+`plugin/index.js`, no `connect()`), the shape `mdk create worker`'s scaffold
+uses. See this skill's main authoring flow
+([`SKILL.md`](../SKILL.md) steps 5-6) and
+[`worker-base-api.md`](./worker-base-api.md#directory-loaded-plugins-workerruntimev2)
+for that model; the rest of this page describes the older shape's conventions.
+
+| Family          | Path | Protocol | Telemetry / commands | Copy it when… |
+| --------------- | ---- | -------- | -------------------- | ------------- |
+| **Avalon**      | [`miners/avalon`](../../../../../../backend/workers/miners/avalon/README.md) | CGMiner ASCII over TCP | 9 / 4 | Plain-text TCP command APIs |
+| **ABB**         | [`power-meter/abb`](../../../../../../backend/workers/power-meter/abb/README.md) | Modbus TCP | 9 / 0 | Modbus register maps; **multi-model**: `MODEL_CLASSES` lookup keyed off `config.model` (B23/B24/M1M20/M4M20/REU615) |
+| **Satec / Schneider** | [`power-meter/satec`](../../../../../../backend/workers/power-meter/satec/README.md), [`power-meter/schneider`](../../../../../../backend/workers/power-meter/schneider/README.md) | Modbus TCP | read-only | Same shape as ABB, single/dual model |
+| **Seneca**      | [`temperature/seneca`](../../../../../../backend/workers/temperature/seneca/README.md) | Modbus TCP | 2 / 0 | Minimal read-only sensor; per-device `register` in config; fault-sentinel semantics (850.0) in the contract |
+| **Antspace**    | [`containers/antspace`](../../../../../../backend/workers/containers/antspace/README.md) | HTTP JSON | 5 / 5 | Cooling containers; model variants (hydro/immersion); approval-gated commands via `constraints` |
+| **Bitdeer**     | [`containers/bitdeer`](../../../../../../backend/workers/containers/bitdeer/README.md) | MQTT | — | Subscription-style transports |
+| **f2pool/ocean** | [`minerpools/f2pool`](../../../../../../backend/workers/minerpools/f2pool/README.md), [`minerpools/ocean`](../../../../../../backend/workers/minerpools/ocean/README.md) | Pool HTTP APIs | — | Non-hardware "device" integrations |
+
+Whatsminer (CGMiner JSON over TCP, AES-encrypted, token auth) is no longer an in-repo family to copy from — it's the
+external [`whatsminer-mdk-worker`](https://github.com/whatsminer/whatsminer-mdk-worker) contract plugin, hosted on
+`WorkerRuntimeV2` via a thin per-deployment adapter (see `examples/mvp-site/backend/whatsminer-adapter.js`). Antminer
+(HTTP CGI, Digest auth) is likewise the external [`antminer-mdk-worker`](https://github.com/bitmain-official/antminer-mdk-worker)
+contract plugin, hosted the same way (see `examples/mvp-site/backend/antminer-adapter.js`).
+
+Do **not** copy from `miners/wm-v3` (empty stub) or model anything on the
+`ThingManager`/`MinerManager` class architecture in [`backend/workers/README.md`](../../../../../../backend/workers/README.md)
+— that's the legacy pre-plugin model.
+
+## Anatomy shared by the module-exporting families
+
+Doesn't apply to the `mdk create worker` scaffold, whose flat directory-loaded layout is
+described in [`worker-base-api.md`](./worker-base-api.md#directory-loaded-plugins-workerruntimev2)
+instead.
+
+```
+<family>/
+├── index.js            # Exports { plugin, start<Family>Worker?, <DeviceClass>? }
+├── plugin/
+│   ├── index.js        # The Worker Plugin
+│   ├── boot.js         # Production families: worker-infra hosting helper
+│   ├── mdk-contract.json
+│   └── src/{telemetry,commands}/*.js
+├── lib/                # Device client class (plain vendor I/O; multi-model families add lib/models/)
+├── mock/server.js      # Firmware simulator
+├── config/             # Sample device configs (production families)
+└── tests/{unit,integration}/
+```
+
+Conventions that hold across every module-exporting family:
+
+- `connect(config, { deviceId })` validates required config keys up front
+  (throwing `ERR_DEVICE_CONFIG_INVALID`-style errors), builds the device
+  client, probes it once, returns it. `disconnect` exists wherever the client
+  holds a socket.
+- Multi-model families select a class from a `MODEL_CLASSES` map keyed by
+  `config.model` / `config.type` (see ABB, Antspace).
+- Handler files mirror contract names 1:1 under `plugin/src/`.
+- Numeric safety is expressed as param `min`/`max` (Whatsminer `setPowerPct`)
+  or an approval `constraints` string (Antspace `resetCoolingSystem`:
+  "Requires two approvals."). Prefer declaring both for physical setpoints.
+- Tests are brittle, split `tests/unit/` (handlers against the mock) and
+  `tests/integration/` (plugin hosted end-to-end).
+
+## The shared mock framework 
+
+[`backend/workers/mock/`](../../../../../../backend/workers/mock/README.md)
+
+Per-family mocks are thin leaves over `@tetherto/mdk-worker-mock`:
+`BaseMock` (CLI, initial-state loading, lifecycle) → category mock
+([`miner.mock.js`](../../../../../../backend/workers/mock/miner.mock.js) resolves commands to `cmds/<command>.js` files,
+[`powermeter.mock.js`](../../../../../../backend/workers/mock/powermeter.mock.js) pins Modbus, 
+[`sensor.mock.js`](../../../../../../backend/workers/mock/sensor.mock.js) reuses it,
+[`container.mock.js`](../../../../../../backend/workers/mock/container.mock.js), 
+[`minerpool.mock.js`](../../../../../../backend/workers/mock/minerpool.mock.js)) → device leaf
+(`<family>/mock/server.js`, e.g. `class WhatsminerMock extends MinerMock`
+with `static dir/TYPES/defaultPort` and a `createTransport()` override).
+Transports live in [`mock/transports/`](../../../../../../backend/workers/mock/transports/) (tcp, http, modbus, mqtt).
+
+A standalone Worker (like the template) can instead ship a self-contained
+`mock/server.js` exporting `createServer(opts) → { server, state, exit }` —
+that's the pattern the smoke harness and template tests use.

package/dist/skills/mdk-worker-plugin/references/local-testing.md

@@ -0,0 +1,134 @@
+# Local testing — no site required
+
+Load this when verifying a Worker. A Worker is site-agnostic, so the entire
+loop below runs on your machine against the Worker's own device mock. Run the
+steps in order; each catches a different failure class.
+
+## 1. Contract validation (static, no runtime)
+
+```
+node <this-skill>/scripts/validate-contract.mjs <worker>/mdk-contract.json
+```
+
+Schema conformance + handler-file existence + duplicate names + the
+numeric-bounds rule. Exit 0/1. Fix and re-run until clean — everything later
+assumes a valid contract.
+
+## 2. In-process smoke (plugin + mock, no Kernel, no DHT)
+
+```
+node <this-skill>/scripts/worker-smoke.mjs <worker-dir>
+```
+
+The harness loads `@tetherto/mdk-worker` as the worker dir resolves it (run
+`npm install` there first). Only if that fails does it fall back to
+`backend/core/mdk-worker` in the MDK checkout that contains the skill itself,
+never above that repo's root. `MDK_WORKER_BASE=<dir>` overrides both.
+
+The harness looks for `<worker-dir>/smoke.config.js` (the template ships one):
+`setup()` boots the device mock and returns `{ config, commands?, teardown }`.
+The harness then:
+
+1. Loads the contract through the real `loadContract` (catching handler wiring
+   errors exactly as `WorkerRuntimeV2` construction would).
+2. Builds one device instance via `createInstance` and calls **every declared
+   telemetry handler**, asserting each returns a defined value of the
+   contract-declared type.
+3. Replicates the Kernel dispatcher's param validation to assert that every
+   bounded numeric param **rejects below-min / above-max** and accepts the
+   bounds themselves.
+4. Executes each command listed in `smoke.config.js` `commands` with its
+   sample in-bounds params and asserts success.
+
+Alternative to `smoke.config.js`: pass `--config '<json>'` (or a path to a
+`.json`/`.js` config module) if the mock is already running.
+
+## 3. Standalone protocol check (WorkerRuntimeV2, real envelopes, still no Kernel)
+
+Host the package's directory on the runtime and drive envelopes through
+`handleRequest` — this exercises envelope dispatch and multi-device routing.
+Minimal caller (run the
+body inside an `async function main ()` in a `.js` file, or as-is in an
+`.mjs`):
+
+```js
+'use strict'
+const path = require('path')
+const WorkerRuntimeV2 = require('<repo>/backend/core/mdk-worker/lib/worker-runtime-v2')
+
+const runtime = new WorkerRuntimeV2(path.resolve('<your-worker-dir>'), {
+  workerId: 'standalone-check',
+  devices: [{ deviceId: 'dev-0', config: { host: '127.0.0.1', port: MOCK_PORT } }]
+})
+await runtime.start() // no kernelTopic → HRPC up, but nothing announced
+
+const res = await runtime.handleRequest({
+  id: 'req-1', version: '0.2.0', type: 'request', action: 'telemetry.pull',
+  sender: 'standalone-check', target: null, deviceId: 'dev-0',
+  timestamp: Date.now(), payload: { query: { type: 'metrics' } }
+})
+console.log(res.payload.metrics)
+await runtime.stop()
+```
+
+Check here: `identity.request`, `capability.request` (handler paths must be
+stripped), `telemetry.pull` per channel, `command.request` success and
+`FAILED` paths, and behavior with the mock stopped (the affected channel's
+handler call errors; siblings and other channels are unaffected — there is no
+boot-time probe and no offline state to hold the device in).
+
+## 4. Site integration (a real Kernel)
+
+In a CLI-managed project (Worker scaffolded with `mdk create worker`, listed
+under `mdk.yaml` → `spec.workers`), this step is just `mdk run worker <name>`
+followed by `mdk run kernel` (or `mdk run` to boot both together) — see
+`mdk-deployment`. `mdk status` then confirms registration.
+
+Otherwise, your Worker package doesn't need to live in the MDK monorepo for
+this step — a caller can require it from anywhere; you only need a local
+Kernel to register against. In a checkout of the MDK monorepo, drop the Worker into the
+mvp-site example: [`examples/mvp-site/deploy/run-process.js`](../../../../../../examples/mvp-site/deploy/run-process.js)
+runs one PM2-supervised process per role (mocks, Kernel, each Worker, Gateway) — add a role that boots your Worker
+and list it under `pm2.roles` in `config/site.deploy.json` (the `worker-antminer` role and
+[`examples/mvp-site/backend/antminer-adapter.js`](../../../../../../examples/mvp-site/backend/antminer-adapter.js) show the
+third-party-plugin shape, no worker-infra plumbing).
+Confirm the Kernel registers it, telemetry flows, and commands round-trip.
+
+## Unit tests (accompany every step)
+
+Pattern (`tests/unit/handlers.test.js`): boot the mock on a free port, build one
+device instance with `createInstance({ dir, entries: loadContract(dir).entries,
+device })`, then call handlers directly off `instance.telemetry.get(name)` /
+`instance.commands.get(name)` — plugin-level tests never need `WorkerRuntimeV2`
+(loadContract/createInstance-level wiring is covered by [`worker-smoke.mjs`](../scripts/worker-smoke.mjs)
+already, so these tests are free to focus on handler behavior):
+
+```js
+const { loadContract, createInstance } = require('<repo>/backend/core/mdk-worker')
+
+const dir = path.resolve('<your-worker-dir>')
+const instance = createInstance({
+  dir,
+  entries: loadContract(dir).entries,
+  device: { id: 'test-0', opts: { host: '127.0.0.1', port: MOCK_PORT }, env: {}, config: {} }
+})
+
+const value = await instance.telemetry.get('hashrate_rt')({})
+const result = await instance.commands.get('setPowerMode')({ mode: 'eco' })
+```
+
+[`backend/workers/miners/avalon/tests/unit/miner.test.js`](../../../../../../backend/workers/miners/avalon/tests/unit/miner.test.js)
+is a worked example of brittle tests in this repo. Runner is **brittle** (no mocha, no
+jest). It must be a `devDependency` of the worker, pinned like the rest of the
+repo (`"brittle": "3.18.0"`); `--no-install` makes `npx` fail instead of
+downloading an unpinned copy when it is missing:
+
+```
+npm install --save-dev --save-exact brittle@3.18.0   # once, if package.json lacks it
+npx --no-install brittle tests/unit/*.test.js
+```
+
+Cover at minimum: every telemetry handler against mock values, every command's
+effect on mock state, a telemetry handler's error when nothing listens (there
+is no boot-time probe to hold the device offline instead), and one
+firmware-error path surfacing its contract `ERR_*` code.

package/dist/skills/mdk-worker-plugin/references/mdk-contract.schema.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$comment": "This schema describes a static Worker Plugin contract. Runtime device IDs and connection configuration belong to the host process and are reported dynamically by WorkerRuntime identity responses; they are intentionally not embedded here.",
+  "title": "MDK Device-Lib Contract Schema",
+  "description": "Formal JSON Schema defining the unified programmatic and semantic capabilities contract for MDK device integration workers.",
+  "type": "object",
+  "required": [
+    "metadata",
+    "capabilities"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "metadata": {
+      "type": "object",
+      "description": "Identity and family metadata defining what the worker represents.",
+      "required": ["provider", "deviceFamily", "brand", "modelsSupported", "overview"],
+      "properties": {
+        "provider": { "type": "string", "description": "The corporate or individual provider behind the worker (e.g., 'microbt')." },
+        "deviceFamily": { "type": "string", "description": "The broad category of devices (e.g., 'miner', 'sensor', 'switchgear')." },
+        "brand": { "type": "string", "description": "The human-readable brand name of the device." },
+        "modelsSupported": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "List of specific models this specific contract supports."
+        },
+        "overview": { 
+          "type": "string", 
+          "description": "Mandatory semantic overview. Used to instruct AI agents on the broad purpose and critical environmental constraints for this device group." 
+        }
+      }
+    },
+    "capabilities": {
+      "type": "object",
+      "description": "The unified machine and semantic capabilities mapping for the device.",
+      "required": ["telemetry", "commands", "health", "errors"],
+      "properties": {
+        "telemetry": {
+          "type": "array",
+          "description": "Metrics continuously updated and read from the device. Natural semantic rules should be appended to the 'description' field.",
+          "items": {
+            "type": "object",
+            "required": ["name", "type", "handler", "description"],
+            "properties": {
+              "name": { "type": "string" },
+              "unit": { "type": "string" },
+              "type": { "type": "string", "enum": ["number", "string", "boolean", "object", "array"] },
+              "handler": { "type": "string", "description": "CommonJS handler path relative to the Worker Plugin directory. Removed from the contract published to Kernel." },
+              "description": { "type": "string", "description": "Human and AI readable metric description. Should include semantic boundaries (e.g., 'If 0, device is booting')." }
+            }
+          }
+        },
+        "commands": {
+          "type": "array",
+          "description": "Callable operations the device accepts.",
+          "items": {
+            "type": "object",
+            "required": ["name", "handler"],
+            "properties": {
+              "name": { "type": "string" },
+              "handler": { "type": "string", "description": "CommonJS handler path relative to the Worker Plugin directory. Removed from the contract published to Kernel." },
+              "description": { "type": "string", "description": "What the command does physically." },
+              "constraints": { "type": "string", "description": "Strict semantic limits (e.g., 'Do not call more than once every 15 minutes')." },
+              "examples": {
+                "type": "array",
+                "description": "Concrete AI instruction workflows for how to utilize this command optimally.",
+                "items": {
+                  "type": "object",
+                  "required": ["intent", "steps"],
+                  "properties": {
+                    "intent": { "type": "string", "description": "The goal or overarching reason for executing the workflow." },
+                    "steps": { "type": "array", "items": { "type": "string" }, "description": "Step-by-step numbered execution plan for the AI." }
+                  }
+                }
+              },
+              "params": {
+                "type": "array",
+                "description": "Input arguments required by the command.",
+                "items": {
+                  "type": "object",
+                  "required": ["name", "type"],
+                  "properties": {
+                    "name": { "type": "string" },
+                    "type": { "type": "string", "enum": ["number", "string", "boolean", "object"] },
+                    "required": { "type": "boolean", "description": "Whether the command handler requires this parameter." },
+                    "enum": {
+                      "type": "array",
+                      "description": "Allowed values. WorkerRuntime rejects a command whose value is not listed (ERR_PARAM_ENUM) before the handler runs.",
+                      "items": {}
+                    },
+                    "min": { "type": "number", "description": "Allowed minimum value (for numbers)." },
+                    "max": { "type": "number", "description": "Allowed maximum value (for numbers)." }
+                  }
+                }
+              },
+              "verify": {
+                "type": "object",
+                "description": "Device-state readback after the command settles. Kernel pulls the `telemetry` metric until it equals the request's `param` value (verification VERIFIED) or `withinMs` passes (UNVERIFIED).",
+                "required": ["telemetry", "param"],
+                "properties": {
+                  "telemetry": { "type": "string", "description": "Name of a telemetry entry that reports the state this command sets." },
+                  "param": { "type": "string", "description": "Name of the command param holding the requested value." },
+                  "withinMs": { "type": "number", "minimum": 1, "description": "How long to keep reading back before UNVERIFIED. Default 60000." }
+                }
+              }
+            }
+          }
+        },
+        "config": {
+          "type": "object",
+          "description": "Device configuration models.",
+          "properties": {
+            "schema": { "type": "string", "description": "Reference identifier for config payload shape." }
+          }
+        },
+        "health": {
+          "type": "object",
+          "description": "Standardized diagnostic mappings.",
+          "required": ["supportedStates"],
+          "properties": {
+            "supportedStates": { "type": "array", "items": { "type": "string" } },
+            "alerts": { "type": "array", "items": { "type": "string" } },
+            "troubleshooting": { 
+              "type": "array", 
+              "items": { "type": "string" },
+              "description": "Semantic AI reasoning array. Provides if-then remediation workflows for specific failures."
+            }
+          }
+        },
+        "errors": {
+          "type": "object",
+          "description": "Lookup table mapping specific device error codes to human/AI-readable text.",
+          "additionalProperties": { "type": "string" }
+        }
+      }
+    }
+  }
+}