Capability Registry and Core Capability Classes

This document defines the MHS capability class format, the five verbs, the versioning and lifecycle rules for classes, the unit and numeric rules, the extension namespace rules, and the OpenMHS 0.9 core class catalogue. The catalogue in §7 and the machine-readable file capabilities.json are generated from one source and MUST agree; where they disagree, the JSON file wins and the Markdown is in error.

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, MAY and OPTIONAL are to be interpreted as described in RFC 2119 and RFC 8174.

1. Why capabilities, not device types

An MHS device is a bag of typed capabilities bound to resources (00-architecture.md A2, informative). The unit of interoperability is therefore a capability class — a versioned, schema-bearing description of one class of action — plus a binding of that class to a concrete resource in a concrete device manifest.

This split exists because device categories do not survive contact with reality. A microscope and a robot arm both expose observe and actuate; what differs is the capability class, its units and its safety envelope. Conversely, one product category (say "liquid handler") spans devices whose pipetting semantics differ in precision, tip coupling, volume range and error behaviour. Classes are shared; bindings carry the vendor truth.

A capability class is not a driver method and not an MCP tool. It is the contract that both must project faithfully. MCP tools, CLI subcommands and code API methods are generated from the class plus binding; they do not add semantics.

2. Class identity and versioning

2.1 Identity

A capability class is identified by capability_id, which MUST match the capabilityId pattern in defs.schema.json (^(cap|x-cap)\.[a-z0-9_.-]+\.v[0-9]+$). The identifier has three parts:

cap . fluid.aspirate . v1
 │      │                └─ class MAJOR version (integer, no MINOR)
 │      └─ class path: domain[.subdomain].name, lowercase, dot-separated
 └─ core namespace (cap) or extension namespace (cap.x / x-cap)

The class path is not a hierarchy that implies inheritance. cap.fluid.transfer.v1 does not "extend" cap.fluid.dispense.v1; any semantic relation is declared explicitly through supersedes or notes.

CAP-001. A capability class identifier MUST contain exactly one .v<major> suffix and that suffix MUST be the last dot-separated element.

CAP-002. A capability class identifier, once published in the MHS Capability Registry, MUST NOT be reassigned to a different contract. Deleting and later reusing a class id is prohibited.

2.2 MAJOR versioning of classes

Capability classes version independently of the wire protocol (00-architecture.md D7, informative). The class id carries the MAJOR version. A new MAJOR is required when any of the following changes in a way that can break a correct client:

1. an input property is removed, renamed, or made REQUIRED;
2. a property's type, unit, or meaning changes;
3. an output property that clients rely on is removed or retyped;
4. the verb changes;
5. the safety envelope semantics are tightened in a way that can reject inputs that were previously accepted and the class is advertised as stable;
6. the set of resource kinds the class binds to shrinks incompatibly.

A new MAJOR is not required for: adding an OPTIONAL input property, adding an output property, adding tags, hazards, notes, an extra effect, or a relaxed limit. These are MINOR changes recorded in the registry metadata (since, supersedes, changelog); the class id does not change.

CAP-003. Every core class in this document is at MAJOR v1. The registry entry for a class MUST list since as a semantic version: the OpenMHS specification release (MAJOR.MINOR.PATCH of the catalogue's spec_version, 0.9.0 for every class of the 0.9 catalogue) that introduced the class in its current form. since is independent of the class MAJOR (v<major> in the id) and of the wire revision (mhs_version), and is never later than spec_version.

CAP-004. A class document MUST NOT declare additionalProperties: true at the top level of input_schema or output_schema unless it also sets x-mhs-open: true, and core classes MUST NOT do so.

2.3 Lifecycle and status

The same status vocabulary (stable, experimental, deprecated) is used by the error registry (MHS-B).

CAP-005. An endpoint MUST NOT bind an experimental class to a resource unless the device manifest also carries "x-mhs-experimental": true at device level and hello.features contains MHS.CAPABILITY.EXPERIMENTAL_PRESENT. Hosts MUST surface experimental status to the model.

CAP-006. A deprecated class MUST remain callable on endpoints that already bind it for the duration of its deprecation window, and MUST continue to validate against the same schema. Removal of a deprecated class is a MAJOR event handled by MHS-010 §5, not by silently dropping the class from a manifest.

2.4 Relation records

• supersedes names the previous class id that this class replaces. New bindings SHOULD use the superseding class.
• notes carries migration notes.
• A class MUST NOT supersede itself, and cycles are invalid.

CAP-007. If a device manifest binds both a class and its supersedes predecessor, the endpoint MUST expose both and MUST map calls to the same physical operation; it MUST NOT implement divergent behaviour under the two identifiers.

3. Class document format

The normative JSON Schema for a class document is capability.schema.json. A class document has five parts:

CAP-008. A class document MUST validate against capability.schema.json. Registry ingestion MUST reject an invalid class document with MHS.REGISTRY.RECORD_INVALID.

The canonical shape is flat: semantic fields live on the class document, not in a nested semantics object.

{
  "capability_id": "cap.fluid.aspirate.v1",
  "title": "Aspirate liquid",
  "verb": "invoke",
  "resource_kinds": ["lab.liquid_handler", "lab.pipette"],
  "input_schema": {
    "type": "object",
    "properties": {
      "volume": {"type": "number", "minimum": 0, "maximum": 1000, "x-mhs-unit": "uL"}
    },
    "required": ["volume"],
    "additionalProperties": false
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "volume_in_tip": {"type": "number", "x-mhs-unit": "uL"}
    },
    "required": ["volume_in_tip"],
    "additionalProperties": false
  },
  "summary": "Draw a specified volume of liquid from a labware well into a pipette tip.",
  "tags": ["liquid handling", "pipetting", "aspirate", "volume", "labware"],
  "units": {"volume": "uL", "volume_in_tip": "uL"},
  "effects": ["material.transfer", "consumable.use"],
  "hazards": ["cross_contamination", "spill", "bubble_formation", "volume_error"],
  "preconditions": ["tip_attached", "liquid_present", "labware_loaded"],
  "postconditions": ["volume_in_tip >= requested_volume * (1 - tolerance)"],
  "determinism": "exact",
  "typical_duration_ms": 2000,
  "notes": "Binding notes carry action-space or vendor details; migration notes live here too.",
  "constraints": {
    "rate_limit": {"max_per_minute": 60},
    "concurrency": "exclusive",
    "max_duration_ms": 30000,
    "cancellable": true
  },
  "safety": {
    "risk_class": "R1",
    "limits": {"volume": {"min": 0, "max": 1000, "unit": "uL"}}
  },
  "conformance_tests": ["CAP-FLUID-001", "SAFE-R1-002"]
}

CAP-009. summary MUST describe what the action does in the physical world, not what the native API call is. It MUST be usable as model context without the schema. tags MUST contain at least three lowercase phrases and MUST NOT contain vendor marketing claims.

CAP-010. effects MUST be drawn from the effect vocabulary in §6.4 (extension tokens allowed only in an extension namespace) and MUST list every kind of physical change the capability can cause, including consumption of a consumable and emission of energy.

CAP-011. hazards MUST list hazards a competent operator would consider, even when the safety envelope prevents them. An empty hazards array is permitted only for classes whose maximum risk class is R0.

4. Verbs

CAP-012. A class with verb read MUST NOT change device state, revision, or any physical output as a side effect of a successful call; a catalogued read class never advances the revision (core.md CORE-021, CORE-095). If observing requires moving the device (for example an autofocus or a scan), the class MUST be invoke.

CAP-013. A class with verb write MUST declare the affected resource and MUST have every accepted value inside its safety.limits; writes are mutations and obey the same revision, receipt, idempotency and envelope rules as invoke.

CAP-014. Read classes SHOULD carry constraints.concurrency: "shared" so that observation does not contend with actuation unless the device declares that observation requires exclusive access.

CAP-015. A subscribe class MUST declare the stream name, its ordering guarantee and its sampling model in notes; subscriptions are described in MHS-002 §12.

5. Binding a class to a device

A device manifest lists bindings, not class documents (device.schema.json capabilities[]). A binding carries capability_id, resource, and optionally input_schema, output_schema, semantics, constraints, limits, determinism, exclusive, requires_permit, native (MHS-006 §4).

CAP-016. A binding MUST NOT widen the class contract: a binding input schema MUST be an equal or stricter schema than the class input schema, and a binding MUST NOT accept values the class forbids. Endpoints MUST validate against the binding schema, then against the class schema; a value valid for the binding but invalid for the class is a server error (MHS.INTERNAL.SCHEMA_DRIFT).

CAP-017. A binding MUST NOT lower the class safety.risk_class. It MAY raise it (for example a class-2 laser capability bound to a class-3B laser). The device's declared risk class is the maximum over its bindings (00-architecture.md §6.1, informative).

CAP-018. A binding's numeric limits MUST be within the class limits; when the class declares a limit and the binding declares none, the class limit applies. A binding that cannot enforce a class limit MUST NOT be published; it is an adapter defect, not a client responsibility.

CAP-019. A binding MAY weaken the class determinism (for example a seeded simulator class bound to hardware is statistical in practice) and MUST declare the weaker value. It MUST NOT strengthen determinism above the class value without a validation record referenced by the class notes or the device profile.

CAP-020. native MUST be a human-readable reference to the exact native symbol (module/class/function or register/command), not a code snippet. It is documentation for reviewers and is not executed.

CAP-045. Motion and manipulation bindings SHOULD declare the action-space semantics of their native interface in the binding's semantics annotation object or in the device profile: mode (position/velocity/torque/cartesian), joint order and names, scale and offset, controller gains, clipping, and whether cartesian targets are delta or absolute. Different simulators expose identical array shapes with different meaning; the MHS schema carries the shape, and the notes MUST carry the meaning. This is a SHOULD, not a new REQUIRED manifest field, because the fidelity object and capability schemas are closed in OpenMHS 0.9.

6. Units, numerics, time

6.1 Unit rules

CAP-021. Every numeric field that represents a physical quantity MUST carry "x-mhs-unit" with a UCUM code string, at every nesting level, including array items. A physical numeric without a unit is a schema error; ingestion MUST reject it.

CAP-022. Units are UCUM codes as published by the Unified Code for Units of Measure. The OpenMHS 0.9 core catalogue uses only the codes in Table 1. A bridge MUST convert native units to the declared UCUM code at the boundary and MUST NOT expose a unit it has not converted.

CAP-023. A capability MUST NOT declare an implicit conversion. If the native API takes mm and the class takes m, the adapter converts; the schema field is m and the bridge MUST NOT accept a bare number interpreted as mm.

CAP-024. Dimensionless quantities use UCUM 1; percentages use %. Angles use rad or deg as declared — an angle field MUST NOT be ambiguous between them. Absolute temperature uses K or Cel as declared; temperature differences use K and MUST NOT be declared Cel. Time durations use s, ms or min as declared; timestamps use RFC 3339 strings in UTC, never a unit-bearing number.

CAP-025. Numeric ranges (minimum, maximum, exclusiveMinimum, exclusiveMaximum) MUST be expressed in the field's declared unit. A class that declares x-mhs-unit: "uL" and maximum: 1000 means 1000 µL.

CAP-026. Floating-point equality MUST NOT be used as a physical success criterion. Classes that need a tolerance MUST declare it as a property or in postconditions (for example volume_in_tip >= requested_volume * (1 - tolerance)).

Table 1 — UCUM codes used by the OpenMHS 0.9 core catalogue.

6.2 Numbers, identifiers, digests

CAP-027. Counts and indices use JSON integers. Revisions follow the revision definition in defs.schema.json: monotone integers; endpoints above 2^53 emit decimal strings and clients MUST accept both.

CAP-028. Identifiers in inputs use the forms defined by the class: a resource_id (defs.schema.json resourceId), a ULID, or an opaque handle declared with x-mhs-handle: true. A capability MUST NOT require a caller to construct a vendor-specific identifier that the endpoint could resolve itself.

CAP-029. Artifacts larger than 1 MiB (images, point clouds, spectra, logs) MUST be returned as artifact references (mhs+artifact://<endpoint>/<artifact_id>) or base64 with "x-mhs-encoding": "base64", never as unbounded inline arrays.

6.3 Time and deadlines

CAP-030. deadline_ms is a duration from request receipt, not a wall-clock instant (00-architecture.md §4.6, informative). Classes with constraints.max_duration_ms MUST complete or return accepted+operation_id within that budget when invoked without cancellation; the endpoint MUST enforce min(deadline_ms, max_duration_ms).

CAP-031. Classes whose real-world duration cannot be bounded (invoke with typical_duration_ms > constraints.max_duration_ms) MUST be advertised as operations: the endpoint MUST return a receipt with status: "accepted" and an operation_id and MUST deliver progress notifications (MHS-002 §11).

6.4 Effect vocabulary

Effects are tokens in effects. The core vocabulary is:

CAP-032. Extension effect tokens MUST be namespaced x-<vendor>.<token> and MUST be documented in the class notes. Core tokens MUST NOT be redefined.

7. OpenMHS 0.9 core capability catalogue

This section is generated from capabilities.json by python3 MHS/sdk/tools/spec_doctest.py --write-catalogue and checked by --check-catalogue (never edit it by hand). Each entry gives the class identifier, verb, risk class, resource kinds, session modes, since (the OpenMHS specification release that introduced the class), the lifecycle status when it is not stable, requires permit when the class is gated, summary, tags, constraints and the normative input and output JSON Schema. cap.device.configure.v1 is the class behind mhs.resource.write (core.md CORE-022); x-mhs-replaced-by names the protocol method that replaces a deprecated class. The catalogue is the source for MHS-A, for the registry ingestion, for the SDK's generated tool descriptions and for the website capability browser.

Domain codes used below: world (simulation), motion, manipulation, sensing, fluid, sample, imaging, optics, measure, thermal, actuation, compute, process, device.

<!-- BEGIN GENERATED: catalogue (python3 MHS/sdk/tools/spec_doctest.py --write-catalogue) -->

7.1 World (7 classes)

cap.world.reset.v1 — Reset a simulated world

invoke · R0 · determinism seeded · exclusive · modes simulated, hybrid · since 0.9.0 — Reset the simulated world to a scenario start state and return the initial observation. When a seed is supplied the endpoint records it in the receipt; otherwise the endpoint's declared default seed applies. Kinds world.sim. Effects simulation.advance. Hazards none. Tags world reset, simulation start, scenario initialisation, seeded reset, episode start. Constraints cancellable false, max_duration_ms 30000. Notes: A reset advances the device revision. For determinism kind 'seeded', seed_control='reset_required' means the seed MUST be supplied here. Input {"additionalProperties":false,"properties":{"options":{"additionalProperties":true,"properties":{},"type":"object","x-mhs-open":true},"scenario":{"maxLength":120,"type":"string"},"seed":{"minimum":0,"type":"integer"}},"type":"object"} · Output {"additionalProperties":false,"properties":{"observation":{"additionalProperties":true,"properties":{},"type":"object","x-mhs-open":true},"revision":{"minimum":0,"type":"integer"},"seed":{"minimum":0,"type":"integer"}},"required":["observation","seed"],"type":"object"}

cap.world.step.v1 — Advance a simulated world

invoke · R0 · determinism exact · exclusive · modes simulated, hybrid · since 0.9.0 — Advance the simulated world by a bounded number of fixed timesteps, optionally applying an action for each step, and return the resulting observation and terminal flags. Kinds world.sim. Effects simulation.advance. Hazards none. Tags simulation step, advance time, apply action, physics tick, reinforcement learning step. Units reward: 1. Constraints cancellable false, max_duration_ms 5000, rate_limit {"max_per_second": 100, "burst": 10}. Notes: ticks counts fixed simulated timesteps (fidelity.timestep_ms). The receipt's state_hash_after is the state hash after the last tick. Input {"additionalProperties":false,"properties":{"action":{"additionalProperties":true,"properties":{},"type":"object","x-mhs-open":true},"ticks":{"maximum":10000,"minimum":1,"type":"integer"}},"type":"object"} · Output {"additionalProperties":false,"properties":{"observation":{"additionalProperties":true,"properties":{},"type":"object","x-mhs-open":true},"reward":{"type":"number","x-mhs-unit":"1"},"state_hash":{"pattern":"^sha256:[0-9a-f]{64}$","type":"string"},"terminated":{"type":"boolean"},"tick":{"minimum":0,"type":"integer"},"truncated":{"type":"boolean"}},"required":["observation","tick","state_hash"],"type":"object"}

cap.world.state.v1 — Read a simulated world state

read · R0 · determinism exact · shared · modes simulated, hybrid, replay · since 0.9.0 · status deprecated — Return the complete normative state of a simulated world together with its revision and canonical state hash. Kinds world.sim. Effects measurement.capture. Hazards none. Tags world state, simulation observation, state snapshot, read world, deterministic state. Constraints cancellable false, max_duration_ms 2000. Replaced by mhs.resource.read. Notes: Deprecated in 0.9: Duplicate of the protocol method mhs.resource.read. The class stays valid and callable for its deprecation window; new drivers use the protocol method. Input {"additionalProperties":false,"properties":{"fields":{"items":{"maxLength":64,"type":"string"},"maxItems":64,"type":"array"}},"type":"object"} · Output {"additionalProperties":false,"properties":{"revision":{"minimum":0,"type":"integer"},"sampled_at":{"type":"string"},"state":{"additionalProperties":true,"properties":{},"type":"object","x-mhs-open":true},"state_hash":{"pattern":"^sha256:[0-9a-f]{64}$","type":"string"}},"required":["state","state_hash","revision"],"type":"object"}

cap.world.snapshot.v1 — Take a world snapshot

invoke · R0 · determinism exact · shared · modes simulated, hybrid · since 0.9.0 · status deprecated — Capture a restorable snapshot of the complete world state, including the revision and state hash, for deterministic restore later. Kinds world.sim. Effects simulation.advance. Hazards none. Tags snapshot, save state, checkpoint, restore point, deterministic capture. Constraints cancellable false, max_duration_ms 10000. Replaced by mhs.snapshot. Notes: Deprecated in 0.9: Duplicate of the protocol method mhs.snapshot (Sim profile). The class stays valid and callable for its deprecation window; new drivers use the protocol method. Requires fidelity.snapshot_restore = true; otherwise MHS.MODE.SNAPSHOT_UNSUPPORTED. Input {"additionalProperties":false,"properties":{},"type":"object"} · Output {"additionalProperties":false,"properties":{"revision":{"minimum":0,"type":"integer"},"snapshot":{"additionalProperties":true,"properties":{},"type":"object","x-mhs-open":true},"snapshot_digest":{"pattern":"^sha256:[0-9a-f]{64}$","type":"string"}},"required":["snapshot","snapshot_digest","revision"],"type":"object"}

cap.world.restore.v1 — Restore a world snapshot

invoke · R0 · determinism exact · exclusive · modes simulated, hybrid · since 0.9.0 · status deprecated — Restore the world to a previously captured snapshot, replacing the current state; the device revision advances and the state hash MUST equal the snapshot's. Kinds world.sim. Effects simulation.advance. Hazards none. Tags restore, load state, rollback, checkpoint restore, deterministic rewind. Constraints cancellable false, max_duration_ms 30000. Replaced by mhs.restore. Notes: Deprecated in 0.9: Duplicate of the protocol method mhs.restore (Sim profile). The class stays valid and callable for its deprecation window; new drivers use the protocol method. Only valid in simulated or replay mode and only when fidelity.snapshot_restore is true. Input {"additionalProperties":false,"properties":{"snapshot":{"additionalProperties":true,"properties":{},"type":"object","x-mhs-open":true}},"required":["snapshot"],"type":"object"} · Output {"additionalProperties":false,"properties":{"revision":{"minimum":0,"type":"integer"},"state_hash":{"pattern":"^sha256:[0-9a-f]{64}$","type":"string"}},"required":["revision","state_hash"],"type":"object"}

cap.world.render.v1 — Render a simulation frame

invoke · R0 · determinism exact · shared · modes simulated, hybrid · since 0.9.0 — Render the current simulated world through a named camera and return an image artifact reference. Rendering does not advance simulated time. Kinds world.sim. Effects measurement.capture. Hazards none. Tags render, camera, visualisation, image capture, headless rendering. Constraints cancellable false, max_duration_ms 30000. Input {"additionalProperties":false,"properties":{"camera":{"maxLength":64,"type":"string"},"format":{"enum":["png","jpeg","rgb_array"],"type":"string"},"height":{"maximum":8192,"minimum":1,"type":"integer"},"width":{"maximum":8192,"minimum":1,"type":"integer"}},"required":["width","height"],"type":"object"} · Output {"additionalProperties":false,"properties":{"height":{"minimum":1,"type":"integer"},"image_ref":{"type":"string"},"media_type":{"type":"string"},"width":{"minimum":1,"type":"integer"}},"required":["image_ref","width","height"],"type":"object"}

cap.world.seed.v1 — Set the world RNG seed

write · R0 · determinism exact · exclusive · modes simulated, hybrid · since 0.9.0 — Set the seed used by the simulated world's random number generators for subsequent steps, without resetting the world. The accepted seed is echoed in the receipt. Kinds world.sim. Effects simulation.advance. Hazards none. Tags seed, random seed, reproducibility, determinism control, rng. Constraints cancellable false, max_duration_ms 2000. Notes: Only meaningful when fidelity.determinism.seed_control is parameter or reset_required. Input {"additionalProperties":false,"properties":{"seed":{"minimum":0,"type":"integer"}},"required":["seed"],"type":"object"} · Output {"additionalProperties":false,"properties":{"accepted":{"type":"boolean"},"seed":{"minimum":0,"type":"integer"}},"required":["seed","accepted"],"type":"object"}

7.2 Motion (9 classes)

cap.motion.joint_position.v1 — Move joints to positions

invoke · R1 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 — Command one or more actuated joints to target positions in joint space, optionally over a declared duration, and report whether the target was reached within tolerance. Kinds robot.arm, motion.axis. Effects motion.joint. Hazards pinch, collision, unexpected_contact. Tags joint motion, move arm, joint position, trajectory, position control. Units duration_s: s, joint_positions: rad, tolerance_rad: rad. Class limits {"joint_positions":{"reason":"joint travel limits are declared per binding"}}. Constraints cancellable true, max_duration_ms 120000. Notes: Position limits, velocity limits and joint-order conventions MUST be declared per binding in safety.envelope. Input {"additionalProperties":false,"properties":{"block":{"type":"boolean"},"duration_s":{"minimum":0,"type":"number","x-mhs-unit":"s"},"joint_positions":{"items":{"type":"number","x-mhs-unit":"rad"},"maxItems":64,"minItems":1,"type":"array"}},"required":["joint_positions"],"type":"object"} · Output {"additionalProperties":false,"properties":{"duration_ms":{"minimum":0,"type":"integer"},"joint_positions":{"items":{"type":"number","x-mhs-unit":"rad"},"type":"array"},"reached":{"type":"boolean"},"tolerance_rad":{"minimum":0,"type":"number","x-mhs-unit":"rad"}},"required":["reached","joint_positions"],"type":"object"}

cap.motion.joint_velocity.v1 — Command joint velocities

invoke · R1 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 — Command continuous joint velocities for a bounded duration. The operation stops at the end of the duration or when cancelled. Kinds robot.arm, motion.axis. Effects motion.joint. Hazards pinch, collision. Tags joint velocity, velocity control, continuous motion, jog, bounded motion. Units duration_s: s, joint_velocities: rad/s. Class limits {"joint_velocities":{"reason":"velocity limits are declared per binding"}}. Constraints cancellable true, max_duration_ms 60000. Input {"additionalProperties":false,"properties":{"duration_s":{"maximum":60,"minimum":0,"type":"number","x-mhs-unit":"s"},"joint_velocities":{"items":{"type":"number","x-mhs-unit":"rad/s"},"maxItems":64,"minItems":1,"type":"array"}},"required":["joint_velocities","duration_s"],"type":"object"} · Output {"additionalProperties":false,"properties":{"applied":{"type":"boolean"},"joint_velocities":{"items":{"type":"number","x-mhs-unit":"rad/s"},"type":"array"}},"required":["applied"],"type":"object"}

cap.motion.joint_torque.v1 — Command joint torques

invoke · R2 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 · status experimental · requires permit — Apply commanded joint torques for a bounded duration for compliant or force-controlled motion. Torque magnitude is bounded by the binding safety envelope. Kinds robot.arm. Effects motion.joint. Hazards pinch, high_force, collision. Tags torque control, compliance, force control, joint torque, impedance. Units duration_s: s, joint_torques: N.m. Class limits {"joint_torques":{"reason":"torque limits are declared per binding; exceeding them is MHS.SAFETY.ENVELOPE_VIOLATION"}}. Constraints cancellable true, max_duration_ms 10000. Input {"additionalProperties":false,"properties":{"duration_s":{"maximum":10,"minimum":0,"type":"number","x-mhs-unit":"s"},"joint_torques":{"items":{"type":"number","x-mhs-unit":"N.m"},"maxItems":64,"minItems":1,"type":"array"}},"required":["joint_torques","duration_s"],"type":"object"} · Output {"additionalProperties":false,"properties":{"applied":{"type":"boolean"},"joint_torques":{"items":{"type":"number","x-mhs-unit":"N.m"},"type":"array"}},"required":["applied"],"type":"object"}

cap.motion.cartesian_pose.v1 — Move to a Cartesian pose

invoke · R1 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 — Move the tool centre point to a Cartesian position and orientation in a named frame. The endpoint solves inverse kinematics; an unreachable target is rejected before motion. Kinds robot.arm. Effects motion.cartesian. Hazards pinch, collision, unreachable_target. Tags cartesian motion, move to pose, inverse kinematics, tool centre point, waypoint. Units duration_s: s, orientation.pitch: rad, orientation.roll: rad, orientation.yaw: rad, position.x: mm, position.y: mm, position.z: mm, tolerance_mm: mm. Class limits {"position":{"reason":"workspace bounds are declared per binding"}}. Constraints cancellable true, max_duration_ms 120000. Input {"additionalProperties":false,"properties":{"duration_s":{"minimum":0,"type":"number","x-mhs-unit":"s"},"frame":{"enum":["base","tool"],"type":"string"},"orientation":{"additionalProperties":false,"properties":{"pitch":{"type":"number","x-mhs-unit":"rad"},"roll":{"type":"number","x-mhs-unit":"rad"},"yaw":{"type":"number","x-mhs-unit":"rad"}},"required":["roll","pitch","yaw"],"type":"object"},"position":{"additionalProperties":false,"properties":{"x":{"type":"number","x-mhs-unit":"mm"},"y":{"type":"number","x-mhs-unit":"mm"},"z":{"type":"number","x-mhs-unit":"mm"}},"required":["x","y","z"],"type":"object"}},"required":["position"],"type":"object"} · Output {"additionalProperties":false,"properties":{"position":{"additionalProperties":false,"properties":{"x":{"type":"number","x-mhs-unit":"mm"},"y":{"type":"number","x-mhs-unit":"mm"},"z":{"type":"number","x-mhs-unit":"mm"}},"type":"object"},"reached":{"type":"boolean"},"tolerance_mm":{"minimum":0,"type":"number","x-mhs-unit":"mm"}},"required":["reached"],"type":"object"}

cap.motion.cartesian_twist.v1 — Command a Cartesian twist

invoke · R1 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 · status experimental — Move with a commanded linear and angular velocity for a bounded duration, in a named frame. Kinds robot.arm. Effects motion.cartesian. Hazards pinch, collision. Tags velocity motion, twist, cartesian velocity, teleoperation, servo. Units angular.x: rad/s, angular.y: rad/s, angular.z: rad/s, duration_s: s, linear.x: m/s, linear.y: m/s, linear.z: m/s, stopped_position.x: mm, stopped_position.y: mm, stopped_position.z: mm. Class limits {"linear":{"reason":"speed limits are declared per binding"}}. Constraints cancellable true, max_duration_ms 60000. Input {"additionalProperties":false,"properties":{"angular":{"additionalProperties":false,"properties":{"x":{"type":"number","x-mhs-unit":"rad/s"},"y":{"type":"number","x-mhs-unit":"rad/s"},"z":{"type":"number","x-mhs-unit":"rad/s"}},"required":["x","y","z"],"type":"object"},"duration_s":{"maximum":60,"minimum":0.01,"type":"number","x-mhs-unit":"s"},"frame":{"enum":["base","tool"],"type":"string"},"linear":{"additionalProperties":false,"properties":{"x":{"type":"number","x-mhs-unit":"m/s"},"y":{"type":"number","x-mhs-unit":"m/s"},"z":{"type":"number","x-mhs-unit":"m/s"}},"required":["x","y","z"],"type":"object"}},"required":["linear","angular","duration_s"],"type":"object"} · Output {"additionalProperties":false,"properties":{"applied":{"type":"boolean"},"stopped_position":{"additionalProperties":false,"properties":{"x":{"type":"number","x-mhs-unit":"mm"},"y":{"type":"number","x-mhs-unit":"mm"},"z":{"type":"number","x-mhs-unit":"mm"}},"type":"object"}},"required":["applied"],"type":"object"}

cap.motion.mobile_base.v1 — Drive a mobile base

invoke · R2 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 — Drive a mobile base with a commanded linear and angular velocity for a bounded duration, or to a target pose. Obstacle and zone limits are enforced by the binding safety envelope. Kinds robot.mobile_base. Effects motion.mobile. Hazards collision, person_in_workspace, tip_over. Tags mobile robot, base motion, drive, navigation, differential drive. Units angular_velocity: rad/s, distance_m: m, duration_s: s, heading_rad: rad, linear_velocity: m/s. Class limits {"angular_velocity":{"reason":"maximum turn rate is declared per binding"},"linear_velocity":{"reason":"maximum transit speed is declared per binding"}}. Constraints cancellable true, max_duration_ms 300000. Input {"additionalProperties":false,"properties":{"angular_velocity":{"type":"number","x-mhs-unit":"rad/s"},"duration_s":{"maximum":300,"minimum":0,"type":"number","x-mhs-unit":"s"},"linear_velocity":{"type":"number","x-mhs-unit":"m/s"}},"required":["linear_velocity","angular_velocity","duration_s"],"type":"object"} · Output {"additionalProperties":false,"properties":{"distance_m":{"minimum":0,"type":"number","x-mhs-unit":"m"},"heading_rad":{"type":"number","x-mhs-unit":"rad"},"stopped":{"type":"boolean"}},"required":["distance_m","heading_rad"],"type":"object"}

cap.motion.stop.v1 — Stop motion safely

invoke · R1 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 — Stop all motion on the resource with a declared deceleration profile and report the stopping position. This capability is always cancellable=false and is exempt from rate limiting. Kinds robot.arm, robot.mobile_base, motion.axis. Effects motion.joint. Hazards collision. Tags stop, halt, decelerate, safe stop, emergency deceleration. Units deceleration: m/s2. Constraints cancellable false, max_duration_ms 5000. Notes: motion.stop is the declared safe-state achievement for many devices; endpoints MUST NOT rate-limit or permit-gate it. Input {"additionalProperties":false,"properties":{"deceleration":{"minimum":0,"type":"number","x-mhs-unit":"m/s2"}},"type":"object"} · Output {"additionalProperties":false,"properties":{"stopped":{"type":"boolean"},"stopped_at":{"type":"string"},"stopped_position":{"additionalProperties":true,"properties":{},"type":"object","x-mhs-open":true}},"required":["stopped"],"type":"object"}

cap.motion.home.v1 — Home the axes

invoke · R1 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 · status experimental — Drive axes to their declared home position or reference switch, establishing the coordinate reference needed by other motion capabilities. Kinds robot.arm, motion.axis. Effects motion.joint. Hazards pinch, collision. Tags homing, reference, calibration motion, home position, axis setup. Units joint_positions: rad, speed_scale: 1. Constraints cancellable true, max_duration_ms 300000. Notes: Homing moves are motion; they are NOT a substitute for mhs.safety.reset and MUST be rejected while the device is latched. Input {"additionalProperties":false,"properties":{"axes":{"items":{"maxLength":64,"type":"string"},"maxItems":32,"type":"array"},"speed_scale":{"maximum":1,"minimum":0,"type":"number","x-mhs-unit":"1"}},"type":"object"} · Output {"additionalProperties":false,"properties":{"axes":{"items":{"maxLength":64,"type":"string"},"type":"array"},"homed":{"type":"boolean"},"joint_positions":{"items":{"type":"number","x-mhs-unit":"rad"},"type":"array"}},"required":["homed"],"type":"object"}

cap.motion.estop.v1 — Engage the device emergency stop

invoke · R0 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 · status deprecated — Engage the device-level emergency stop: motion stops within the declared latency, outputs transition to the declared safe state, and the device latches until mhs.safety.reset. Kinds robot.arm, robot.mobile_base, motion.axis, world.sim. Effects safety.estop. Hazards collision, person_in_workspace, unexpected_energy. Tags emergency stop, e-stop, halt device, safety stop, latch. Constraints cancellable false, max_duration_ms 2000. Replaced by mhs.safety.estop. Notes: Deprecated in 0.9: Duplicate of the protocol method mhs.safety.estop; endpoints route it to the same latch. The class stays valid and callable for its deprecation window; new drivers use the protocol method. motion.estop is the capability-level expression of mhs.safety.estop. Both MUST reach the same latch. MHS is never a safety-rated channel (MHS-000 6.3). Input {"additionalProperties":false,"properties":{"reason":{"maxLength":500,"minLength":1,"type":"string"}},"required":["reason"],"type":"object"} · Output {"additionalProperties":false,"properties":{"engaged":{"type":"boolean"},"latched":{"type":"boolean"},"latency_ms":{"minimum":0,"type":"integer"},"safe_state_achieved":{"type":"boolean"}},"required":["engaged","latched"],"type":"object"}

7.3 Manipulation (4 classes)

cap.manipulation.grasp.v1 — Grasp an object

invoke · R1 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 — Close the gripper on a target object with a bounded force and report the achieved grasp width. A failed grasp is a completed operation with grasped=false, not a silent success. Kinds robot.gripper, robot.arm. Effects manipulation.grasp. Hazards pinch, object_damage, collision. Tags grasp, gripper close, pick object, force grasp, contact. Units force: N, width: mm, width_mm: mm. Class limits {"force":{"reason":"grasp force limit is declared per binding"}}. Constraints cancellable true, max_duration_ms 30000. Input {"additionalProperties":false,"properties":{"approach":{"enum":["top","side","front"],"type":"string"},"force":{"minimum":0,"type":"number","x-mhs-unit":"N"},"width":{"minimum":0,"type":"number","x-mhs-unit":"mm"}},"type":"object"} · Output {"additionalProperties":false,"properties":{"grasped":{"type":"boolean"},"width_mm":{"minimum":0,"type":"number","x-mhs-unit":"mm"}},"required":["grasped"],"type":"object"}

cap.manipulation.release.v1 — Release a grasped object

invoke · R1 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 · status experimental — Open the gripper to release the held object, optionally to a declared opening width, and report the achieved width. Kinds robot.gripper. Effects manipulation.release. Hazards object_damage, drop. Tags release, gripper open, drop object, ungrasp, place handoff. Units open_width: mm, width_mm: mm. Constraints cancellable true, max_duration_ms 10000. Input {"additionalProperties":false,"properties":{"open_width":{"minimum":0,"type":"number","x-mhs-unit":"mm"}},"type":"object"} · Output {"additionalProperties":false,"properties":{"released":{"type":"boolean"},"width_mm":{"minimum":0,"type":"number","x-mhs-unit":"mm"}},"required":["released"],"type":"object"}

cap.manipulation.place.v1 — Place an object at a target

invoke · R2 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 — Place the held object at a declared target location with an approach height, release the gripper and verify the object is no longer held. Kinds robot.arm, robot.gripper. Effects manipulation.grasp, material.move. Hazards collision, object_damage, sample_loss. Tags place, put down, deposit, assembly, position object. Units placement_height: mm. Constraints cancellable true, max_duration_ms 120000. Input {"additionalProperties":false,"properties":{"placement_height":{"minimum":0,"type":"number","x-mhs-unit":"mm"},"release_after":{"type":"boolean"},"target":{"additionalProperties":true,"properties":{},"type":"object","x-mhs-open":true}},"required":["target"],"type":"object"} · Output {"additionalProperties":false,"properties":{"placed":{"type":"boolean"},"target_revision":{"minimum":0,"type":"integer"}},"required":["placed"],"type":"object"}

cap.manipulation.pick.v1 — Pick an object from a source

invoke · R2 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 — Move to a declared source, grasp the object, lift it by a declared clearance and verify the grasp still holds. Combines cartesian motion and grasp under one receipt. Kinds robot.arm, robot.gripper. Effects manipulation.grasp, motion.cartesian. Hazards collision, object_damage, sample_loss. Tags pick, pick and place, retrieve, lift object, bin picking. Units lift_clearance: mm. Constraints cancellable true, max_duration_ms 180000. Input {"additionalProperties":false,"properties":{"approach":{"enum":["top","side","front"],"type":"string"},"lift_clearance":{"minimum":0,"type":"number","x-mhs-unit":"mm"},"source":{"additionalProperties":true,"properties":{},"type":"object","x-mhs-open":true}},"required":["source"],"type":"object"} · Output {"additionalProperties":false,"properties":{"grasped":{"type":"boolean"},"lifted":{"type":"boolean"},"object_id":{"maxLength":128,"type":"string"}},"required":["grasped"],"type":"object"}

7.4 Sensing (5 classes)

cap.sensing.read.v1 — Read a sensor

read · R0 · determinism statistical · shared · modes hardware, simulated, hybrid, replay · since 0.9.0 — Read the current value of one or more sensor channels and return the values with a sampling timestamp and a monotone sequence number. Volatile channels are also available by subscription. Kinds sensor, sensor.imu, sensor.force_torque. Effects measurement.capture. Hazards none. Tags sensor read, telemetry, measurement, observation, channel value. Constraints cancellable false, max_duration_ms 2000. Input {"additionalProperties":false,"properties":{"fields":{"items":{"maxLength":64,"type":"string"},"maxItems":64,"type":"array"}},"type":"object"} · Output {"additionalProperties":false,"properties":{"sampled_at":{"type":"string"},"sequence":{"minimum":0,"type":"integer"},"values":{"additionalProperties":true,"properties":{},"type":"object","x-mhs-open":true}},"required":["values","sampled_at"],"type":"object"}

cap.sensing.image.v1 — Capture an image

invoke · R0 · determinism statistical · shared · modes hardware, simulated, hybrid, replay · since 0.9.0 — Capture a single image from a named camera with a declared resolution and exposure and return an image artifact reference. Kinds sensor.camera. Effects measurement.capture. Hazards privacy. Tags camera, image capture, snapshot, vision, photograph. Units exposure_ms: ms. Constraints cancellable false, max_duration_ms 30000. Input {"additionalProperties":false,"properties":{"camera":{"maxLength":64,"type":"string"},"exposure_ms":{"minimum":0,"type":"number","x-mhs-unit":"ms"},"format":{"enum":["png","jpeg","raw"],"type":"string"},"height":{"maximum":8192,"minimum":1,"type":"integer"},"width":{"maximum":8192,"minimum":1,"type":"integer"}},"type":"object"} · Output {"additionalProperties":false,"properties":{"exposure_ms":{"minimum":0,"type":"number","x-mhs-unit":"ms"},"height":{"minimum":1,"type":"integer"},"image_ref":{"type":"string"},"media_type":{"type":"string"},"width":{"minimum":1,"type":"integer"}},"required":["image_ref","width","height"],"type":"object"}

cap.sensing.point_cloud.v1 — Capture a point cloud

invoke · R0 · determinism statistical · shared · modes hardware, simulated, hybrid, replay · since 0.9.0 — Capture a depth point cloud over a declared range and return a point-cloud artifact reference with the point count and coordinate frame. Kinds sensor.depth. Effects measurement.capture. Hazards privacy. Tags point cloud, depth, lidar, 3d scan, range image. Units max_range: mm, min_range: mm. Constraints cancellable false, max_duration_ms 60000. Input {"additionalProperties":false,"properties":{"frame":{"maxLength":64,"type":"string"},"max_points":{"maximum":10000000,"minimum":1,"type":"integer"},"max_range":{"minimum":0,"type":"number","x-mhs-unit":"mm"},"min_range":{"minimum":0,"type":"number","x-mhs-unit":"mm"}},"type":"object"} · Output {"additionalProperties":false,"properties":{"artifact_ref":{"type":"string"},"frame":{"maxLength":64,"type":"string"},"point_count":{"minimum":0,"type":"integer"}},"required":["artifact_ref","point_count"],"type":"object"}

cap.sensing.force_torque.v1 — Read a force/torque sensor

read · R0 · determinism statistical · shared · modes hardware, simulated, hybrid, replay · since 0.9.0 — Read the current force and torque vector in a declared frame and return the wrench with its sampling timestamp. Kinds sensor.force_torque. Effects measurement.capture. Hazards high_force. Tags force torque, wrench, contact force, load cell, six axis. Units force: N, torque: N.m. Constraints cancellable false, max_duration_ms 2000. Input {"additionalProperties":false,"properties":{"axes":{"items":{"enum":["x","y","z","rx","ry","rz"],"type":"string"},"maxItems":6,"type":"array"},"frame":{"enum":["tool","base"],"type":"string"}},"type":"object"} · Output {"additionalProperties":false,"properties":{"force":{"items":{"type":"number","x-mhs-unit":"N"},"maxItems":3,"minItems":3,"type":"array"},"sampled_at":{"type":"string"},"saturated":{"type":"boolean"},"torque":{"items":{"type":"number","x-mhs-unit":"N.m"},"maxItems":3,"minItems":3,"type":"array"}},"required":["force","torque","sampled_at"],"type":"object"}

cap.sensing.imu.v1 — Read an IMU

read · R0 · determinism statistical · shared · modes hardware, simulated, hybrid, replay · since 0.9.0 — Read linear acceleration, angular velocity and orientation from an inertial measurement unit, with the declared reference frame and timestamp. Kinds sensor.imu. Effects measurement.capture. Hazards none. Tags imu, accelerometer, gyroscope, orientation, inertial. Units angular_velocity: rad/s, linear_acceleration: m/s2, orientation.w: 1, orientation.x: 1, orientation.y: 1, orientation.z: 1. Constraints cancellable false, max_duration_ms 2000. Notes: Quaternion components are dimensionless (UCUM 1); the unit is carried here, not implied by convention. Input {"additionalProperties":false,"properties":{"frame":{"enum":["body","world"],"type":"string"}},"required":["frame"],"type":"object"} · Output {"additionalProperties":false,"properties":{"angular_velocity":{"items":{"type":"number","x-mhs-unit":"rad/s"},"maxItems":3,"minItems":3,"type":"array"},"linear_acceleration":{"items":{"type":"number","x-mhs-unit":"m/s2"},"maxItems":3,"minItems":3,"type":"array"},"orientation":{"additionalProperties":false,"properties":{"w":{"type":"number","x-mhs-unit":"1"},"x":{"type":"number","x-mhs-unit":"1"},"y":{"type":"number","x-mhs-unit":"1"},"z":{"type":"number","x-mhs-unit":"1"}},"required":["x","y","z","w"],"type":"object"},"sampled_at":{"type":"string"}},"required":["linear_acceleration","angular_velocity","sampled_at"],"type":"object"}