@tetherto/mdk-worker 0.0.0-stage → 0.12.1

package/README.md

@@ -1,3 +1,207 @@
-# Temporary Holding Version
+# @tetherto/mdk-worker
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`WorkerRuntime` hosts a Worker Plugin's devices behind one HRPC channel to Kernel. Every
+Worker package in this monorepo (miners, containers, power meters, temperature, minerpools, …) constructs a
+`WorkerRuntime` from its own boot function; see [Workers](../../workers/README.md) for the plugin side of that
+contract.
+
+## What this package exports
+
+```js
+const { WorkerRuntime, loadPlugin, loadContract, createInstance, createModuleContext } = require('@tetherto/mdk-worker')
+```
+
+- `WorkerRuntime`: starts the Hyperswarm RPC server, dispatches MDK Protocol actions to per-device handlers, and
+  persists the DHT/RPC keypair. It creates `opts.storeDir` owner-only (mode `0700`) and writes any file-backed seed
+  `0600`, so the Worker's identity stays readable only by its owner
+- `loadPlugin`: loads a plugin object (`mdk-contract.json`, handlers, ...) from a directory
+- `loadContract`, `createInstance`, `createModuleContext` — the loader internals `loadPlugin` composes
+
+## Store services
+
+> [!CAUTION]
+> **Deprecated.** Store services are the legacy thing/adapter Worker surface: `opts.services`, the built-ins in this
+> section, `ctx.services` in handlers, and the `@tetherto/mdk-core` layer behind them
+> ([`createWorkerInfra`](../mdk/lib/worker-infra.js), the `*Service` classes, and the `Thing` base classes the in-repo
+> device drivers extend). Nothing is removed, because the in-repo Workers still run on it. Build a new Worker as a
+> directory-loaded package on `WorkerRuntimeV2` with no `services`, the shape
+> [Build a third-party Worker](../../../docs/guides/workers/build-a-worker.md) walks through.
+>
+> MDK has no `WorkerRuntimeV2` equivalent yet for:
+>
+> - Adding or removing devices at runtime (`registerThing`, `updateThing`, `forgetThings`): a `WorkerRuntimeV2` device
+>   list is fixed at construction, so a device change is a config edit and a restart
+> - Store-backed history and aggregates (`logs`, `historical_logs`, `logs_multi`, `stats`) and pool `ext_data`
+> - Device comments and Worker settings
+> - Kernel write actions (`pushAction`): the Kernel resolves candidate writes with `write.calls.request`, which only a
+>   Worker with the `actions` service answers
+
+A [`WorkerRuntime`](lib/worker-runtime.js) host can inject an `opts.services` object naming which of the store-backed
+capabilities below to serve. When present, [`service-builtins.js`](lib/service-builtins.js) answers the matching
+queries and commands directly from a host-managed persisted store — never from the plugin's device handlers. A
+Worker Plugin that doesn't need any of this passes `services: null`; see
+[Build a third-party Worker](../../../docs/guides/workers/build-a-worker.md)'s minimal reference implementation.
+
+Each entry activates only when its named service exists on `opts.services`:
+
+| Service      | Telemetry it activates  | Commands it activates | What it needs implemented         |
+|--------------|-------------------------|-----------------------|-----------------------------------|
+| `logHistory` | `logs`, `historical_logs`, `logs_multi` | — | `tailLog({thingId, ...})`, `getHistoricalLogs({thingId, ...})` |
+| `settings`   | `settings` | `saveSettings` | `getSettings()`, `saveSettingsEntries(params)`        |
+| `provisioning` | `thing_config`, `list`, `count`, `config` | `registerThing`, `updateThing`, `forgetThings` | `getThingConf`, `listDevices`, `listDeviceIds`, `registerThing`, `updateThing`, `forgetThings` |
+| `stats`      | `stats` | — | `aggrStats(deviceIds, opts)` |
+| `comments`   | — | `saveComment`, `editComment`, `deleteComment` | `saveThingComment`, `editThingComment`, `deleteThingComment` |
+| `actions`    | `write.calls.request` (wired directly in `WorkerRuntime.handleRequest`, not through the builtin tables) | — | `getWriteCalls(payload)` |
+| `pool`       | `ext_data` (scheduler-driven pool Workers) | — | `getWrkExtData({query})`           |
+| `snaps`      | used only inside the `list` builtin, for `params.status` snapshot enrichment | — | `getLast(deviceId)` |
+
+These never reach plugin handlers — they are Worker infrastructure, not device translation. When `provisioning` is
+active, its `list` builtin shadows the runtime's own bare `{ deviceId, status }` device list with the fuller thing
+list (`{ id, code, type, tags, info, comments, address, port, ... }`) some gateways read.
+
+> [!IMPORTANT]
+> Built-in commands must be published into the contract or the Kernel dispatcher rejects them
+> (`ERR_COMMAND_NOT_IN_CAPABILITIES`) before they ever reach the runtime. [`mergeBuiltinCommands`](lib/service-builtins.js)
+> handles this: it deep-clones the plugin's contract and appends one entry per *active* builtin command
+> (`registerThing`, `updateThing`, `forgetThings`, `saveSettings`, `saveComment`, `editComment`, `deleteComment`) —
+> the source contract is never mutated, and without `services` (or with every builtin inactive) the original contract
+> reference is returned unchanged.
+
+`allowEmptyDevices` (a `WorkerRuntime` constructor option, not a service) is the usual pairing with `provisioning`:
+a fresh host boots with zero devices, takes `registerThing` writes to populate the store, and picks up the
+provisioned set on its next restart. See [Build a third-party Worker](../../../docs/guides/workers/build-a-worker.md)'s
+troubleshooting section for the constructor-level error (`ERR_DEVICES_REQUIRED`).
+
+Every in-repo device Worker (Avalon, Antspace, Bitdeer, ABB, SATEC, Schneider, Seneca) wires this surface through
+[`createWorkerInfra`](../mdk/lib/worker-infra.js), which builds the `store`, `services`, and provisioning-first
+`devices` list a `WorkerRuntime` needs, then hands the constructed `services` object straight to
+`new WorkerRuntime(plugin, { ..., services, allowEmptyDevices: true })`. The Ocean and F2Pool pool Workers inject only
+a `pool` service. Reading [`miners/avalon/plugin/boot.js`](../../workers/miners/avalon/plugin/boot.js) alongside this
+section is the fastest way to see the whole surface exercised end to end. Whatsminer and Antminer are
+manufacturer-maintained external Workers, listed in
+[`backend/workers/external-workers.json`](../../workers/external-workers.json), hosted on `WorkerRuntimeV2` with no
+`services`.
+
+## Caller allowlist
+
+The Worker RPC server is **fail-closed**. Only public keys on its allowlist may connect; unknown keys are rejected at
+connect time and every request is re-checked (`ERR_WORKER_CALLER_NOT_ALLOWED`), so `revokeKey()` applies to open
+connections. Every request is envelope-validated (`validateFull`) before dispatch.
+
+```js
+const runtime = new WorkerRuntime(plugin, {
+  workerId: 'rack-1',
+  devices,
+  allowedKeys: [kernel.getClientPublicKey()] // the key the Kernel dials Workers with
+})
+runtime.allowKey(gatewayClientKeyHex)        // more callers, before or after start()
+runtime.revokeKey(hex)
+runtime.getAllowedKeys()
+await runtime.start()
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `allowedKeys` | `[]` | Hex/Buffer public keys allowed to call. `start()` throws `ERR_WORKER_ALLOWED_KEYS_REQUIRED` when empty |
+| `allowAll` | `false` | Admit every DHT peer that learns the Worker key. Development only; logs a warning at start |
+| `bootstrap` | HyperDHT public bootstrap | Bootstrap nodes for the Worker's HyperDHT node; pass the same list to every component on a private DHT network |
+
+Admit the Kernel's **client** key (`kernel.getClientPublicKey()`), not its listener key (`getPublicKey()`). Add a Gateway or other client
+key only when deliberately granting direct Worker access; every admitted key can issue supported commands, regardless of its Kernel role.
+`@tetherto/mdk-core` adds callers automatically for local stacks:
+`trustKernel(runtime, kernel)` adds write-capable Kernel callers in-process, and `trustKeysFromDir(runtime, dir)` adds every published
+key across processes. Omit those helpers when enforcing a Kernel-only Worker allowlist. The
+[site security blueprint](../../../docs/guides/security/index.md#step-3-isolate-workers-and-devices) explains who gets access and what that access allows.
+Every in-repo Worker boot function forwards `allowedKeys` /
+`allowAll` to the runtime.
+
+## Request hardening
+
+The Worker RPC key is reachable without going through the Kernel, so the runtime does not trust the caller to have
+checked anything:
+
+- **Command params** are validated against the contract's declared `params` (`type`, `required`, `enum`, `min`/`max`)
+  before the handler runs, after positional (`{ value }` / `{ args }`) normalization. Undeclared keys pass through;
+  a `null` or missing optional param is skipped. The built-in commands are checked against their published entries
+  too. Arrays pass an `object` param (the schema has no `array` type).
+- **Device id lists** in `logs_multi` and `stats` must be arrays of strings, at most `MAX_DEVICE_IDS` (1000) long.
+- **Addressing:** the envelope's `deviceId` always wins over a `thingId`/`id` key in params; worker-scoped requests
+  (`deviceId: null`) keep the caller's key.
+- **Errors over RPC:** handler and service errors whose message starts with `ERR_` are returned as-is. Anything else
+  is logged locally (`DEBUG=mdk:worker:runtime`) and replaced by `ERR_TELEMETRY_FAILED`, `ERR_COMMAND_FAILED` or
+  `ERR_REQUEST_FAILED`, so driver messages carrying addresses or credentials never leave the process. Throw
+  `ERR_*` errors from handlers for anything the caller should see.
+- **Built-in `health` telemetry** (`WorkerRuntimeV2`) returns only `{ status, id, workerId }`; `env`, device `opts`
+  and `config` are never returned.
+- **Seed files** (`storeDir`): an existing seed that is not exactly 32 bytes fails start with
+  `ERR_SEED_FILE_MALFORMED` instead of being replaced (which would rotate the Worker's identity). Symlinks
+  (`ERR_SEED_FILE_SYMLINK`), non-regular files (`ERR_SEED_FILE_INVALID`) and files owned by another user
+  (`ERR_SEED_FILE_OWNER`) are refused; group/other permission bits are stripped to `0600`. New seeds are created
+  exclusively (`O_EXCL`) with mode `0600`.
+
+## Errors
+
+The plugin and contract loaders validate their inputs and throw on the first problem; the request handlers instead
+return these codes on the response envelope's `error` field rather than throwing.
+
+| Code | Fires when | Fix |
+| --- | --- | --- |
+| `ERR_COMMAND_FAILED` | A command handler or built-in service throws an error whose message does not start with `ERR_` (details are logged locally) | Check the Worker's `mdk:worker:runtime` debug log; throw `ERR_*` errors from handlers |
+| `ERR_CONTRACT_DIR_REQUIRED` | `loadContract` is called without a non-empty package-directory string | Pass the plugin package directory as `pkgDir` |
+| `ERR_CONTRACT_INVALID_JSON` | The package's `mdk-contract.json` cannot be parsed as JSON | Correct the JSON syntax in `mdk-contract.json` |
+| `ERR_CONTRACT_NOT_FOUND` | `mdk-contract.json` cannot be read in the package directory | Ensure `mdk-contract.json` exists in the package directory |
+| `ERR_DEVICE_CONFIG_INVALID` | A device spec supplies `config` that is not an object | Pass `config` as an object or omit it |
+| `ERR_DEVICE_ID_DUPLICATE` | Two device specs share the same `deviceId` | Give each device a unique `deviceId` |
+| `ERR_DEVICE_ID_MISSING` | A device spec has no non-empty string `deviceId` | Give every device spec a `deviceId` string |
+| `ERR_DEVICE_ID_REQUIRED` | A non-metrics telemetry query or a device command arrives with no `deviceId` | Include the target `deviceId` in the request |
+| `ERR_DEVICE_INSTANCE_MISSING` | A handler is invoked for a device that has no open instance | Register the device and open its instance before invoking handlers |
+| `ERR_DEVICE_NOT_FOUND` | A request targets a `deviceId` the Worker does not hold | Target a `deviceId` the Worker manages |
+| `ERR_DEVICE_UNAVAILABLE` | A telemetry or command request targets a device that is not online | Wait for the device to reconnect and come online before retrying |
+| `ERR_DEVICES_REQUIRED` | The runtime is started with an empty or missing device list where empty is not allowed | Supply at least one device spec |
+| `ERR_INSTANCE_DEVICE_ID_REQUIRED` | `createInstance` is called with a device that has no non-empty `id` | Give the device object an `id` string |
+| `ERR_INSTANCE_DEVICE_REQUIRED` | `createInstance` is called without a device object | Pass a `device` object to `createInstance` |
+| `ERR_INSTANCE_DIR_REQUIRED` | `createInstance` is called without a non-empty `dir` string | Pass the plugin directory as `dir` |
+| `ERR_INSTANCE_ENTRIES_REQUIRED` | `createInstance` is called without an `entries` object | Pass the resolved `entries` map |
+| `ERR_INSTANCE_HANDLER_LOAD_FAILED` | A handler module throws while being loaded | Fix the error inside the handler module |
+| `ERR_INSTANCE_HANDLER_NOT_FOUND` | A handler file path in the contract cannot be resolved | Correct the handler path in the contract |
+| `ERR_INSTANCE_HANDLER_NOT_FUNCTION` | A resolved handler module does not export a function | Export a function from the handler module |
+| `ERR_MODULE_CONTEXT_DIR_REQUIRED` | The module context is created without a non-empty `dir` string | Pass a directory when creating the module context |
+| `ERR_NO_DEVICE_CONTEXT` | `@tetherto/mdk-worker/device` is required outside a plugin instance | Load the plugin via `createInstance({ dir, entries, device })` so the device context exists |
+| `ERR_PARAM_ENUM` | A command param is not one of its declared `enum` values | Send one of the declared values |
+| `ERR_PARAM_RANGE` | A numeric command param is outside its declared `min`/`max`, or a `deviceIds` list is longer than 1000 | Send a value in range; split long device lists |
+| `ERR_PARAM_REQUIRED` | A param declared `required: true` is missing or `null` | Include the param |
+| `ERR_PARAM_TYPE` | A command param does not match its declared `type`, or `deviceIds` is not an array of strings | Send the declared type |
+| `ERR_PARAMS_INVALID` | Command `params` is not an object after positional normalization | Send `params` as an object |
+| `ERR_PLUGIN_CONNECT_NOT_FUNCTION` | The plugin's `connect` is not a function | Provide a `connect` function on the plugin |
+| `ERR_PLUGIN_CONTRACT_CAPABILITIES_MISSING` | The contract has no `capabilities` object | Add a `capabilities` object to the contract |
+| `ERR_PLUGIN_CONTRACT_METADATA_MISSING` | The contract has no `metadata` object | Add a `metadata` object to the contract |
+| `ERR_PLUGIN_CONTRACT_MISSING` | The plugin carries no contract object | Provide the plugin's contract |
+| `ERR_PLUGIN_DIR_MISSING` | The plugin has no non-empty `dir` string | Set the plugin's `dir` |
+| `ERR_PLUGIN_DISCONNECT_NOT_FUNCTION` | The plugin defines `disconnect` as something other than a function | Make `disconnect` a function or omit it |
+| `ERR_PLUGIN_DUPLICATE_NAME` | Two entries in a contract section share a name | Give each entry in the section a unique name |
+| `ERR_PLUGIN_ENTRY_NAME_MISSING` | A contract section entry has no non-empty `name` | Give every entry a `name` |
+| `ERR_PLUGIN_HANDLER_MISSING` | A contract entry has no non-empty `handler` path | Set the entry's `handler` path |
+| `ERR_PLUGIN_HANDLER_NOT_FOUND` | An entry's handler file cannot be required | Correct the entry's handler path |
+| `ERR_PLUGIN_HANDLER_NOT_FUNCTION` | An entry's handler module does not export a function | Export a function from the handler |
+| `ERR_PLUGIN_LOAD_HANDLER_NOT_FUNCTION` | `loadHandler` is provided but is not a function | Pass a function for `loadHandler` or omit it |
+| `ERR_PLUGIN_REQUIRED` | `loadPlugin` is called without a plugin object | Pass a plugin object to `loadPlugin` |
+| `ERR_PLUGIN_SECTION_NOT_ARRAY` | A contract capabilities section is present but is not an array | Make each capabilities section an array |
+| `ERR_REQUEST_FAILED` | The RPC responder fails before or outside action dispatch (for example an undecodable request) | Send a well-formed MDK envelope |
+| `ERR_SEED_FILE_INVALID` | A seed path in `storeDir` is not a regular file | Remove the entry so a new seed can be created |
+| `ERR_SEED_FILE_MALFORMED` | A seed file in `storeDir` is not exactly 32 bytes | Restore the seed from backup, or delete it to accept a new Worker identity |
+| `ERR_SEED_FILE_OWNER` | A seed file in `storeDir` is owned by another user | Run the Worker as the file's owner or fix the ownership |
+| `ERR_SEED_FILE_SYMLINK` | A seed path in `storeDir` is a symbolic link | Replace the link with the real file |
+| `ERR_TELEMETRY_FAILED` | A telemetry handler or built-in query throws an error whose message does not start with `ERR_` (details are logged locally) | Check the Worker's `mdk:worker:runtime` debug log; throw `ERR_*` errors from handlers |
+| `ERR_UNKNOWN_ACTION` | An envelope carries an action the runtime does not handle | Send a supported action |
+| `ERR_UNKNOWN_COMMAND` | A command request names a command the plugin does not define | Send a command declared in the contract |
+| `ERR_UNKNOWN_QUERY_TYPE` | A telemetry query names a type the plugin does not provide | Query a telemetry type declared in the contract |
+| `ERR_WORKER_DIR_REQUIRED` | WorkerRuntimeV2 is started without a non-empty `dir` string | Pass the Worker package directory as `dir` |
+| `ERR_WORKER_ID_REQUIRED` | The runtime is constructed without a `workerId` string | Pass a `workerId` string |
+
+## Next steps
+
+See:
+
+- [`backend/core/docs/README.md`](../docs/README.md#worker-runtime-tethertomdk-worker): where this package sits
+  in Core's dependency graph
+- [Workers](../../workers/README.md): the plugin packages this runtime hosts

package/device.js

@@ -0,0 +1,15 @@
+'use strict'
+
+/**
+ * The ambient per-instance device, required by handler files as
+ * `require('@tetherto/mdk-worker/device')` and resolving to that instance's
+ * frozen { id, opts, env, config, workerId, logger }.
+ *
+ * Inside an instance the request never reaches this file: lib/instance-loader.js
+ * intercepts it and hands back the device the instance was created with. This
+ * file exists to make the specifier resolvable and to fail with a pointer at
+ * createInstance() when a plugin module is required outside an instance — a test
+ * requiring a handler directly, say — instead of leaving the plugin with
+ * `undefined` where its device should be.
+ */
+throw new Error('ERR_NO_DEVICE_CONTEXT: @tetherto/mdk-worker/device is only available inside a plugin instance; load the plugin with createInstance({ dir, entries, device }) from @tetherto/mdk-worker')

package/index.js

@@ -0,0 +1,12 @@
+'use strict'
+
+module.exports = {
+  WorkerRuntime: require('./lib/worker-runtime'),
+  WorkerRuntimeV2: require('./lib/worker-runtime-v2'),
+  loadPlugin: require('./lib/plugin-loader').loadPlugin,
+  loadContract: require('./lib/contract-loader').loadContract,
+  validateContract: require('./lib/contract-validator').validateContract,
+  validateParams: require('./lib/param-validator').validateParams,
+  createInstance: require('./lib/instance-loader').createInstance,
+  createModuleContext: require('./lib/module-context').createModuleContext
+}

package/lib/contract-loader.js

@@ -0,0 +1,74 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const { loadPlugin } = require('./plugin-loader')
+
+const CONTRACT_FILE = 'mdk-contract.json'
+
+/**
+ * Load a Worker Plugin from a directory: <pkgDir>/mdk-contract.json is the
+ * package's only index. Structural validation is plugin-loader's (same
+ * ERR_PLUGIN_* errors for a missing metadata/capabilities object, a missing
+ * handler field or a duplicate name), and every handler path is resolved on
+ * disk — but never executed. A handler module reads its device from the
+ * ambient '@tetherto/mdk-worker/device', which only exists inside an instance,
+ * so requiring one here would either throw or bind the wrong device.
+ *
+ * Returns { dir, contract, publishedContract, entries }, where `entries` is
+ * { telemetry: Map, commands: Map } of name -> resolved handler file: the input
+ * createInstance() binds once per device.
+ */
+function loadContract (pkgDir) {
+  if (typeof pkgDir !== 'string' || !pkgDir) throw new Error('ERR_CONTRACT_DIR_REQUIRED')
+
+  const file = path.join(pkgDir, CONTRACT_FILE)
+  let raw
+  try {
+    raw = fs.readFileSync(file, 'utf8')
+  } catch (err) {
+    throw new Error(`ERR_CONTRACT_NOT_FOUND: ${file}: ${err.message}`)
+  }
+
+  let contract
+  try {
+    contract = JSON.parse(raw)
+  } catch (err) {
+    throw new Error(`ERR_CONTRACT_INVALID_JSON: ${file}: ${err.message}`)
+  }
+
+  const entries = { telemetry: new Map(), commands: new Map() }
+  const loaded = loadPlugin({
+    contract,
+    dir: pkgDir,
+    // A directory-loaded plugin has no connect(): WorkerRuntimeV2 builds an
+    // instance per device instead. Only present because v1's shape demands it.
+    connect: _noConnect,
+    loadHandler: (handlerFile, { section, name }) => {
+      entries[section].set(name, require.resolve(handlerFile))
+      return _unbound(section, name)
+    }
+  })
+
+  return {
+    dir: pkgDir,
+    contract: loaded.contract,
+    publishedContract: loaded.publishedContract,
+    entries
+  }
+}
+
+function _noConnect () {
+  throw new Error('ERR_CONTRACT_NO_CONNECT')
+}
+
+// plugin-loader publishes a function per entry; a contract on its own has no
+// process-wide handler to give it, so the placeholder fails loudly rather than
+// silently standing in for a device-bound one.
+function _unbound (section, name) {
+  return () => {
+    throw new Error(`ERR_HANDLER_NOT_BOUND: ${section}.${name}`)
+  }
+}
+
+module.exports = { loadContract }

package/lib/contract-validator.js

@@ -0,0 +1,114 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+const SCHEMA_PATH = path.join(__dirname, '..', 'mdk-contract.schema.json')
+
+let _schema = null
+
+function _loadSchema () {
+  if (!_schema) _schema = JSON.parse(fs.readFileSync(SCHEMA_PATH, 'utf8'))
+  return _schema
+}
+
+function _jsonType (v) {
+  if (Array.isArray(v)) return 'array'
+  if (v === null) return 'null'
+  return typeof v
+}
+
+function _matchesType (expected, v) {
+  if (expected === 'integer') return typeof v === 'number' && Number.isInteger(v)
+  return _jsonType(v) === expected
+}
+
+// Implements the JSON Schema subset mdk-contract.schema.json uses (type, enum,
+// required, properties, additionalProperties, items). A schema feature outside
+// this subset would validate as always-passing here; the ajv parity test in
+// backend/workers guards against that drift.
+function _validateNode (schema, value, at, errors) {
+  if (schema.type && !_matchesType(schema.type, value)) {
+    errors.push(`ERR_CONTRACT_TYPE: ${at || '/'} expected ${schema.type}, got ${_jsonType(value)}`)
+    return
+  }
+  if (schema.enum && !schema.enum.includes(value)) {
+    errors.push(`ERR_CONTRACT_ENUM: ${at} is ${JSON.stringify(value)}, allowed: ${schema.enum.join(' | ')}`)
+  }
+  if (_jsonType(value) === 'object') {
+    for (const key of schema.required || []) {
+      if (!(key in value)) errors.push(`ERR_CONTRACT_REQUIRED: ${at || '/'} missing required property '${key}'`)
+    }
+    const props = schema.properties || {}
+    for (const [key, v] of Object.entries(value)) {
+      if (props[key]) {
+        _validateNode(props[key], v, `${at}/${key}`, errors)
+      } else if (schema.additionalProperties === false) {
+        errors.push(`ERR_CONTRACT_UNEXPECTED: ${at || '/'} has unexpected property '${key}'`)
+      } else if (schema.additionalProperties && typeof schema.additionalProperties === 'object') {
+        _validateNode(schema.additionalProperties, v, `${at}/${key}`, errors)
+      }
+    }
+  }
+  if (Array.isArray(value) && schema.items) {
+    value.forEach((v, i) => _validateNode(schema.items, v, `${at}/${i}`, errors))
+  }
+}
+
+// Rules the schema cannot express. Handler existence needs the plugin dir, so
+// it only runs when the caller has one (a fetched external contract does not).
+function _semanticChecks (contract, dir, errors) {
+  if (_jsonType(contract) !== 'object') return
+  const caps = contract.capabilities
+  if (_jsonType(caps) !== 'object') return
+
+  for (const section of ['telemetry', 'commands']) {
+    const entries = Array.isArray(caps[section]) ? caps[section] : []
+    const seen = new Set()
+    entries.forEach((entry, i) => {
+      const at = `/capabilities/${section}/${i}`
+      if (_jsonType(entry) !== 'object') return
+      if (entry.name) {
+        if (seen.has(entry.name)) errors.push(`ERR_CONTRACT_DUPLICATE_NAME: ${at} '${entry.name}' already declared in ${section}`)
+        seen.add(entry.name)
+      }
+      if (dir && typeof entry.handler === 'string' && entry.handler) {
+        const file = path.resolve(dir, entry.handler)
+        if (!fs.existsSync(file)) errors.push(`ERR_CONTRACT_HANDLER_NOT_FOUND: ${at} handler '${entry.handler}' does not exist (resolved: ${file})`)
+      }
+    })
+  }
+
+  const commands = Array.isArray(caps.commands) ? caps.commands : []
+  commands.forEach((cmd, i) => {
+    if (_jsonType(cmd) !== 'object' || !Array.isArray(cmd.params)) return
+    cmd.params.forEach((p, j) => {
+      if (_jsonType(p) !== 'object' || p.type !== 'number') return
+      const at = `/capabilities/commands/${i}/params/${j}`
+      if (typeof p.min !== 'number' || typeof p.max !== 'number') {
+        errors.push(`ERR_CONTRACT_PARAM_BOUNDS_MISSING: ${at} ('${cmd.name}'.'${p.name}') — number params must declare min and max so the Kernel can enforce ERR_PARAM_RANGE`)
+      } else if (p.min > p.max) {
+        errors.push(`ERR_CONTRACT_PARAM_BOUNDS_INVALID: ${at} min ${p.min} > max ${p.max}`)
+      }
+    })
+  })
+}
+
+/**
+ * Validate a parsed mdk-contract.json against the vendored schema, plus the
+ * semantic rules the schema cannot express: unique telemetry/command names,
+ * number params with coherent min/max, and (when opts.dir names the plugin
+ * directory) every handler file present on disk.
+ *
+ * validateContract(contract, { dir?, semantic = true }) -> { ok, errors }
+ * where errors is a list of ERR_CONTRACT_* strings. Pass semantic: false for
+ * schema-only conformance (the catalogue generator's mode).
+ */
+function validateContract (contract, opts = {}) {
+  const errors = []
+  _validateNode(_loadSchema(), contract, '', errors)
+  if (opts.semantic !== false) _semanticChecks(contract, opts.dir, errors)
+  return { ok: errors.length === 0, errors }
+}
+
+module.exports = { validateContract, SCHEMA_PATH }

package/lib/instance-loader.js

@@ -0,0 +1,107 @@
+'use strict'
+
+const path = require('path')
+const debug = require('debug')('mdk:worker:instance-loader')
+const { createModuleContext } = require('./module-context')
+
+const SECTIONS = ['telemetry', 'commands']
+
+// Builtin telemetry entries synthesized into every instance rather than
+// loaded from a contract-declared handler file. Registered only when the
+// plugin's own contract did not already declare a channel of the same name
+// (see createInstance below) — a real plugin handler always wins. Each
+// closes over this instance's own frozen `device`, so calling it is genuine
+// per-device dispatch (`entry.instance.telemetry.get('health')(...)`), not a
+// runtime-level shortcut: it proves the addressed device's own instance
+// answered, the same way any real handler would.
+//
+// The reply is deliberately limited to identifiers: `env` (secrets resolved
+// from mdk.yaml), `opts` (device credentials) and `config` must never leave
+// the process through a telemetry channel any caller can pull.
+const BUILTIN_TELEMETRY = {
+  health: (device) => () => ({
+    status: 'OK',
+    id: device.id,
+    workerId: device.workerId
+  })
+}
+
+/**
+ * Instantiate a directory-loaded Worker Plugin for one device.
+ *
+ * The plugin's own files get a private module registry (see module-context.js),
+ * so everything they do at load time (construct a client, open a store) happens
+ * once per device and their module-level state is that device's.
+ *
+ * createInstance({ dir, entries, device }) -> { telemetry: Map, commands: Map }
+ * of plain (params) functions. `entries` is loadContract().entries; `device` is
+ * what the plugin sees as '@tetherto/mdk-worker/device'. Per handlers HLD §3
+ * this aborts rather than degrades: a handler module that is missing, throws at
+ * load or does not export a function fails here, naming the device.
+ *
+ * `instance.telemetry` also always carries the builtin entries in
+ * BUILTIN_TELEMETRY (e.g. `health`) unless the contract declared a real
+ * channel of the same name — see BUILTIN_TELEMETRY above.
+ */
+function createInstance (opts) {
+  const { dir, entries, device } = opts || {}
+  if (typeof dir !== 'string' || !dir) throw new Error('ERR_INSTANCE_DIR_REQUIRED')
+  if (!entries || typeof entries !== 'object') throw new Error('ERR_INSTANCE_ENTRIES_REQUIRED')
+  if (!device || typeof device !== 'object') throw new Error('ERR_INSTANCE_DEVICE_REQUIRED')
+  if (typeof device.id !== 'string' || !device.id) throw new Error('ERR_INSTANCE_DEVICE_ID_REQUIRED')
+
+  // WorkerRuntimeV2 always sets device.logger (a debug() instance); a device
+  // built by hand (contract-level tests, say) may omit it, so default to a
+  // no-op rather than let a handler's unconditional logger(...) call throw.
+  const ambientDevice = device.logger ? device : { ...device, logger: _noopLogger }
+
+  const context = createModuleContext({
+    dir,
+    ambient: { '@tetherto/mdk-worker/device': ambientDevice },
+    label: `[mdk-instance:${device.id}]`
+  })
+
+  const instance = { telemetry: new Map(), commands: new Map() }
+  for (const section of SECTIONS) {
+    for (const [name, handler] of _pairs(entries[section])) {
+      const where = `${device.id}: ${section}.${name}: ${handler}`
+      const request = path.resolve(context.root, handler)
+
+      let file
+      try {
+        file = context.resolve(request)
+      } catch (err) {
+        throw new Error(`ERR_INSTANCE_HANDLER_NOT_FOUND: ${where}`)
+      }
+
+      let fn
+      try {
+        fn = context.load(file)
+      } catch (err) {
+        throw new Error(`ERR_INSTANCE_HANDLER_LOAD_FAILED: ${where}: ${err.message}`, { cause: err })
+      }
+      if (typeof fn !== 'function') throw new Error(`ERR_INSTANCE_HANDLER_NOT_FUNCTION: ${where}`)
+
+      instance[section].set(name, fn)
+    }
+  }
+
+  for (const [name, build] of Object.entries(BUILTIN_TELEMETRY)) {
+    if (instance.telemetry.has(name)) continue
+    instance.telemetry.set(name, build(device))
+  }
+
+  debug('instance ready for %s (%d private modules)', device.id, context.size)
+  return instance
+}
+
+// loadContract() hands over Maps; plain objects are accepted so a test can
+// build a section by hand.
+function _pairs (section) {
+  if (!section) return []
+  return section instanceof Map ? section : Object.entries(section)
+}
+
+function _noopLogger () {}
+
+module.exports = { createInstance }

package/lib/module-context.js

@@ -0,0 +1,104 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const Module = require('module')
+
+const PRIVATE_EXTENSIONS = new Set(['.js', '.cjs'])
+
+/**
+ * Private module registry for one plugin load — the interception mechanism
+ * behind the ambient context modules ('@tetherto/mdk-worker/device' for worker
+ * instances, and the gateway/MCP equivalents).
+ *
+ * Files under `dir` get their own registry, so module-level state (a client
+ * constructed at load time, say) belongs to this context alone. `node_modules`
+ * and `node:` builtins keep resolving through the shared cache — `debug` and
+ * `node:sqlite` are process singletons, not per-context copies.
+ *
+ * Isolation rests on Node's Module internals (the pattern proxyquire and
+ * friends use): a Module per in-package file, compiled by hand, with `require`
+ * routed back here so in-package requests stay private.
+ *
+ * createModuleContext({ dir, ambient, label }) -> { root, size, resolve, load }.
+ * `ambient` maps specifiers to values; both the bare and `.js` spellings are
+ * intercepted before resolution, so a plugin does not need the host package
+ * installed to require its context. `label` names the synthetic entry parent
+ * in Node's require stack when a resolution fails.
+ */
+function createModuleContext (opts) {
+  const { dir, ambient, label } = opts || {}
+  if (typeof dir !== 'string' || !dir) throw new Error('ERR_MODULE_CONTEXT_DIR_REQUIRED')
+
+  const requests = new Map()
+  for (const [specifier, value] of Object.entries(ambient || {})) {
+    requests.set(specifier, value)
+    requests.set(`${specifier}.js`, value)
+  }
+
+  // Realpath because Node resolves modules through symlinks: a package reached
+  // via a workspace link would otherwise look out-of-package and lose isolation.
+  const root = _realpath(path.resolve(dir))
+  const registry = new Map()
+
+  const isPrivate = (file) => {
+    if (!PRIVATE_EXTENSIONS.has(path.extname(file))) return false
+    const rel = path.relative(root, file)
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return false
+    return !rel.split(path.sep).includes('node_modules')
+  }
+
+  const requireFrom = (parent, request) => {
+    if (requests.has(request)) return requests.get(request)
+    if (Module.isBuiltin(request)) return Module._load(request, parent, false)
+
+    const file = Module._resolveFilename(request, parent, false)
+    if (!isPrivate(file)) return Module._load(request, parent, false)
+    return loadPrivate(file, parent)
+  }
+
+  const loadPrivate = (file, parent) => {
+    const cached = registry.get(file)
+    if (cached) return cached.exports
+
+    const mod = new Module(file, parent)
+    mod.filename = file
+    mod.paths = Module._nodeModulePaths(path.dirname(file))
+    mod.require = (request) => requireFrom(mod, request)
+    // Registered before compiling so a require cycle inside the package sees a
+    // partial exports object instead of recursing, as the shared loader does.
+    registry.set(file, mod)
+    try {
+      mod._compile(fs.readFileSync(file, 'utf8'), file)
+    } catch (err) {
+      registry.delete(file)
+      throw err
+    }
+    mod.loaded = true
+    return mod.exports
+  }
+
+  // Synthetic parent for the context's entry files: it carries the package's
+  // node_modules paths, and names the context in Node's require stack when a
+  // resolution fails.
+  const entryParent = new Module(path.join(root, label || '[mdk-module-context]'), null)
+  entryParent.filename = entryParent.id
+  entryParent.paths = Module._nodeModulePaths(root)
+
+  return {
+    root,
+    get size () { return registry.size },
+    resolve: (request) => Module._resolveFilename(request, entryParent, false),
+    load: (request) => requireFrom(entryParent, request)
+  }
+}
+
+function _realpath (dir) {
+  try {
+    return fs.realpathSync(dir)
+  } catch {
+    return dir
+  }
+}
+
+module.exports = { createModuleContext }