ORK

Overview

The ORK kernel is the trusted coordination kernel at the heart of MDK. It routes commands, monitors device health, registers Workers, and pulls telemetry — without performing user authentication, business logic, or aggregation.

ORK is a pass-through kernel: it receives commands from any caller using @tetherto/mdk-client — most commonly the App Node — and dispatches them to Workers; it pulls telemetry from Workers and routes it back to callers. Everything else is the caller's responsibility.

What ORK owns

ORK is decomposed into single-responsibility modules. Modules communicate only through their declared interfaces.

WorkerRegistry: maps deviceId → workerId → RPC channel. Source of truth for worker-to-device routing. Workers progress through a state machine as ORK discovers and registers them — Unregistered → Discovered → IdentitySaved → Ready → Terminated.

CommandDispatcher: validates incoming command envelopes, resolves the owning Worker from the registry, checks that the command exists in the worker's declared capabilities, then passes it to the state machine.

CommandStateMachine: tracks every command's full execution lifecycle. Backed by a Write-Ahead Log (WAL) in Hyperbee — every state transition is persisted before it takes effect. On restart, recover() sweeps non-terminal states and retries or fails them — QUEUED → DISPATCHED → EXECUTING → SUCCESS (or FAILED / TIMEOUT).

TelemetryCollector: stateless proxy. Routes telemetry.pull queries to the appropriate Worker and passes the response back to the caller. Workers own all aggregation and storage — ORK is a thin router.

Scheduler: system metronome. Runs non-overlapping interval jobs for telemetry pulls, health pings, and state pulls on configurable cadences. Jobs are idempotent — safe to restart with no state loss.

HealthMonitor: ping-based liveness checker. Sends health.ping to every registered Worker on a configurable cadence and updates the registry — UNKNOWN → HEALTHY → SICK → DEAD (with reconnect path back to HEALTHY).

Write-action approval

Write commands that affect fleet state can require multi-party approval before ORK dispatches them to Workers. ORK owns the kernel-side approval modules for this path (protocol version 0.2.0, up from 0.1.0):

ActionManager: owns the approval lifecycle — pushAction(), batch push, vote counting against a negative-vote threshold, and delegating writes to Workers once the configured vote thresholds are met. Invoked via MDK protocol envelopes (action.push, action.vote, action.cancel-batch, and related query actions).

ActionCaller: resolves a staged action into per-Worker write calls (getWriteCalls()) and the permission strings each call requires before execution.

Permissions: evaluates colon-delimited device-family permission strings (for example miner:w or container:w) with hasWritePermission() and hasPermission() against PERMISSION_LEVELS (r, w, rw).

The App Node enforces route-level RBAC (actions:w) before any write-action HTTP route reaches ORK. ORK then checks the required target device-family permissions stored with the action before resolving or approving writes.

The pull-only model

ORK never receives unsolicited data from Workers. It always initiates — pulling telemetry, pinging health, and pulling state on cadences set in opts.cadences. Workers become reachable and wait; ORK reaches out on its own schedule.

This is what prevents the kernel from being overwhelmed by upstream pressure and is why Workers are described as passive. Callers — typically the App Node — do send command requests to ORK (ORK is the receiver for those), but ORK then dispatches each command to the owning Worker via its own initiated call.

Transports

ORK is the passive listener on both transports — the caller always initiates the connection.

• IPC (default): the caller/App Node dials ORK over a Unix socket on the same host. Implicit trust — no allowlist required. The default for single-host and development deployments
• HRPC: the caller/App Node dials ORK over encrypted Hyperswarm Noise streams. ORK maintains an allowlist — the caller/App Node's DHT public key must be added to opts.auth.whitelist before the connection is accepted. Used for remote or multi-host deployments

What ORK does not own

ORK deliberately excludes these concerns and delegates them to other layers:

• User authentication and RBAC: JWT validation, session management, and role-based access are the App Node's responsibility. ORK trusts all messages from any established @tetherto/mdk-client connection without inspecting user identity. The App Node is the only caller that enforces RBAC before reaching ORK; using @tetherto/mdk-client without the App Node carries no access control layer
• Business logic and aggregation: cross-Worker queries, fleet statistics, and site-level aggregation belong in App Node controllers, not in the kernel
• UI and consumer interfaces: ORK has no HTTP surface. Consumers connect through the App Node's REST, WebSocket, or MCP endpoints

Next steps

• Understand approval-gated writes in the MDK request flow
• Submit and approve write actions from the App Node
• Understand the App Node's role as ORK's consumer
• Understand Workers as ORK's downstream
• Choose a deployment shape
• Review the full ORK API and configuration