OpenMHSindependent draft 0.9
Playground
Open menu
MHS-003InformativePart 2 of 2

Capability Registry and Core Capability Classes

OpenMHS 0.9 development draftSections 7.5–1230 min read6,641 words

Part 2 of 2 · MHS-003 continues from Part 1. The document is split only for page size; the requirements are continuous.

On this page 15 sections
  1. 7.5 Fluid (6 classes)
  2. 7.6 Sample (6 classes)
  3. 7.7 Imaging (3 classes)
  4. 7.8 Optics (3 classes)
  5. 7.9 Measure (9 classes)
  6. 7.10 Thermal (1 class)
  7. 7.11 Actuation (3 classes)
  8. 7.12 Compute (2 classes)
  9. 7.13 Process (1 class)
  10. 7.14 Device (4 classes)
  11. 8. Extension namespaces
  12. 9. Deprecation
  13. 10. Generated artifacts and their consumers
  14. 11. Requirements traceability
  15. 12. Informative: choosing between classes

7.5 Fluid (6 classes)

cap.fluid.aspirate.v1 — Aspirate liquid

invoke · R1 · determinism statistical · exclusive · modes hardware, simulated, hybrid · since 0.9.0 — Draw a specified volume of liquid from a declared labware well into a pipette tip, with a bounded flow rate and an optional liquid-level offset. Kinds lab.liquid_handler, lab.pipette. Effects material.transfer, consumable.use. Hazards cross_contamination, spill, bubble_formation, volume_error. Tags liquid handling, pipetting, aspirate, volume, labware. Units aspirated_volume: uL, flow_rate: uL/s, liquid_level_mm: mm, liquid_level_offset: mm, volume: uL. Class limits {"volume":{"max":1000,"min":0,"reason":"pipette tip capacity; bindings declare their actual range","unit":"uL"}}. Constraints cancellable true, max_duration_ms 60000. Notes: Preconditions: tip attached, liquid present, labware loaded. Errors: MHS.DEVICE.PRECONDITION_UNMET with details.precondition. Input {"additionalProperties":false,"properties":{"flow_rate":{"minimum":0,"type":"number","x-mhs-unit":"uL/s"},"liquid_level_offset":{"type":"number","x-mhs-unit":"mm"},"source":{"additionalProperties":false,"properties":{"labware":{"maxLength":128,"type":"string"},"well":{"maxLength":32,"type":"string"}},"required":["labware","well"],"type":"object"},"tip":{"maxLength":64,"type":"string"},"volume":{"maximum":1000,"minimum":0,"type":"number","x-mhs-unit":"uL"}},"required":["volume","source"],"type":"object"} · Output {"additionalProperties":false,"properties":{"aspirated_volume":{"minimum":0,"type":"number","x-mhs-unit":"uL"},"liquid_level_mm":{"type":"number","x-mhs-unit":"mm"},"tip":{"maxLength":64,"type":"string"}},"required":["aspirated_volume"],"type":"object"}

cap.fluid.dispense.v1 — Dispense liquid

invoke · R2 · determinism statistical · exclusive · modes hardware, simulated, hybrid · since 0.9.0 — Dispense a specified volume from the pipette into a declared labware well, with optional blowout and mixing after dispense. Kinds lab.liquid_handler, lab.pipette. Effects material.transfer. Hazards cross_contamination, spill, volume_error. Tags liquid handling, dispense, pipette, well, reagent addition. Units dispensed_volume: uL, flow_rate: uL/s, target_volume_after: uL, volume: uL. Class limits {"volume":{"max":1000,"min":0,"reason":"pipette tip capacity","unit":"uL"}}. Constraints cancellable true, max_duration_ms 60000. Input {"additionalProperties":false,"properties":{"blowout":{"type":"boolean"},"flow_rate":{"minimum":0,"type":"number","x-mhs-unit":"uL/s"},"mix_cycles":{"maximum":100,"minimum":0,"type":"integer"},"target":{"additionalProperties":false,"properties":{"labware":{"maxLength":128,"type":"string"},"well":{"maxLength":32,"type":"string"}},"required":["labware","well"],"type":"object"},"volume":{"maximum":1000,"minimum":0,"type":"number","x-mhs-unit":"uL"}},"required":["volume","target"],"type":"object"} · Output {"additionalProperties":false,"properties":{"dispensed_volume":{"minimum":0,"type":"number","x-mhs-unit":"uL"},"target_volume_after":{"minimum":0,"type":"number","x-mhs-unit":"uL"}},"required":["dispensed_volume"],"type":"object"}

cap.fluid.transfer.v1 — Transfer liquid between wells

invoke · R2 · determinism statistical · exclusive · modes hardware, simulated, hybrid · since 0.9.0 — Aspirate a volume from a source well and dispense it into a target well as one receipted operation, so a failed transfer cannot leave an untracked half-state. Kinds lab.liquid_handler, lab.pipette. Effects material.transfer, consumable.use. Hazards cross_contamination, spill, sample_loss. Tags transfer, pipetting, liquid movement, plate to plate, reagent transfer. Units flow_rate: uL/s, source_volume_after: uL, target_volume_after: uL, transferred_volume: uL, volume: uL. Class limits {"volume":{"max":1000,"min":0,"reason":"pipette tip capacity","unit":"uL"}}. Constraints cancellable true, max_duration_ms 120000. Input {"additionalProperties":false,"properties":{"flow_rate":{"minimum":0,"type":"number","x-mhs-unit":"uL/s"},"mix_cycles":{"maximum":100,"minimum":0,"type":"integer"},"source":{"additionalProperties":false,"properties":{"labware":{"maxLength":128,"type":"string"},"well":{"maxLength":32,"type":"string"}},"required":["labware","well"],"type":"object"},"target":{"additionalProperties":false,"properties":{"labware":{"maxLength":128,"type":"string"},"well":{"maxLength":32,"type":"string"}},"required":["labware","well"],"type":"object"},"tip":{"maxLength":64,"type":"string"},"volume":{"maximum":1000,"minimum":0,"type":"number","x-mhs-unit":"uL"}},"required":["volume","source","target"],"type":"object"} · Output {"additionalProperties":false,"properties":{"source_volume_after":{"minimum":0,"type":"number","x-mhs-unit":"uL"},"target_volume_after":{"minimum":0,"type":"number","x-mhs-unit":"uL"},"transferred_volume":{"minimum":0,"type":"number","x-mhs-unit":"uL"}},"required":["transferred_volume"],"type":"object"}

cap.fluid.mix.v1 — Mix the contents of a well

invoke · R1 · determinism statistical · exclusive · modes hardware, simulated, hybrid · since 0.9.0 · status experimental — Mix the contents of a declared well by repeated aspiration and dispense cycles at a bounded volume and speed. Kinds lab.liquid_handler, lab.pipette. Effects material.transfer. Hazards cross_contamination, bubble_formation, sample_loss. Tags mix, homogenise, resuspend, agitation, well mixing. Units speed: /min, volume: uL. Constraints cancellable true, max_duration_ms 120000. Input {"additionalProperties":false,"properties":{"cycles":{"maximum":100,"minimum":1,"type":"integer"},"speed":{"description":"Mixing rate in aspirate/dispense cycles per minute.","minimum":0,"type":"number","x-mhs-unit":"/min"},"target":{"additionalProperties":false,"properties":{"labware":{"maxLength":128,"type":"string"},"well":{"maxLength":32,"type":"string"}},"required":["labware","well"],"type":"object"},"volume":{"minimum":0,"type":"number","x-mhs-unit":"uL"}},"required":["target","cycles"],"type":"object"} · Output {"additionalProperties":false,"properties":{"cycles":{"minimum":0,"type":"integer"},"mixed":{"type":"boolean"}},"required":["mixed"],"type":"object"}

cap.fluid.wash.v1 — Wash a well or tip

invoke · R1 · determinism statistical · exclusive · modes hardware, simulated, hybrid · since 0.9.0 · status experimental — Wash a declared well or the pipette tip with a bounded volume of wash solution, discarding waste to a declared waste container. Kinds lab.liquid_handler. Effects material.transfer, consumable.use. Hazards cross_contamination, spill, chemical_exposure. Tags wash, rinse, tip wash, well wash, decontamination. Units volume: uL, waste_volume: uL. Constraints cancellable true, max_duration_ms 180000. Input {"additionalProperties":false,"properties":{"cycles":{"maximum":20,"minimum":1,"type":"integer"},"target":{"additionalProperties":false,"properties":{"labware":{"maxLength":128,"type":"string"},"well":{"maxLength":32,"type":"string"}},"type":"object"},"volume":{"minimum":0,"type":"number","x-mhs-unit":"uL"},"waste":{"additionalProperties":false,"properties":{"labware":{"maxLength":128,"type":"string"}},"required":["labware"],"type":"object"}},"required":["cycles","volume","waste"],"type":"object"} · Output {"additionalProperties":false,"properties":{"washed":{"type":"boolean"},"waste_volume":{"minimum":0,"type":"number","x-mhs-unit":"uL"}},"required":["washed"],"type":"object"}

cap.fluid.level.v1 — Read a liquid level

read · R0 · determinism statistical · shared · modes hardware, simulated, hybrid · since 0.9.0 · status experimental — Detect and report the liquid level and estimated volume in a declared container using a declared detection method. Kinds lab.liquid_handler, lab.labware. Effects measurement.capture. Hazards cross_contamination. Tags liquid level, volume estimate, meniscus, capacitance detection, pressure detection. Units confidence: 1, level_mm: mm, volume_uL: uL. Constraints cancellable false, max_duration_ms 10000. Input {"additionalProperties":false,"properties":{"container":{"additionalProperties":false,"properties":{"labware":{"maxLength":128,"type":"string"},"well":{"maxLength":32,"type":"string"}},"required":["labware","well"],"type":"object"},"method":{"enum":["capacitance","pressure","image"],"type":"string"}},"type":"object"} · Output {"additionalProperties":false,"properties":{"confidence":{"maximum":1,"minimum":0,"type":"number","x-mhs-unit":"1"},"detection":{"enum":["capacitance","pressure","image"],"type":"string"},"level_mm":{"minimum":0,"type":"number","x-mhs-unit":"mm"},"volume_uL":{"minimum":0,"type":"number","x-mhs-unit":"uL"}},"required":["level_mm","detection"],"type":"object"}

7.6 Sample (6 classes)

cap.sample.move.v1 — Move a sample or labware

invoke · R1 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 — Move a sample, plate or other labware object from one declared location to another using the device's transport mechanism. Kinds lab.sample, lab.labware. Effects material.move. Hazards sample_loss, drop, collision. Tags move plate, transfer labware, sample transport, plate mover, carrier. Constraints cancellable true, max_duration_ms 120000. Input {"additionalProperties":false,"properties":{"carrier":{"maxLength":64,"type":"string"},"from":{"additionalProperties":false,"properties":{"location":{"maxLength":128,"type":"string"}},"required":["location"],"type":"object"},"sample_id":{"maxLength":128,"type":"string"},"to":{"additionalProperties":false,"properties":{"location":{"maxLength":128,"type":"string"}},"required":["location"],"type":"object"}},"required":["sample_id","from","to"],"type":"object"} · Output {"additionalProperties":false,"properties":{"location":{"maxLength":128,"type":"string"},"moved":{"type":"boolean"},"sample_id":{"maxLength":128,"type":"string"}},"required":["moved","location"],"type":"object"}

cap.sample.incubate.v1 — Incubate samples

invoke · R2 · determinism none · exclusive · modes hardware, simulated, hybrid · since 0.9.0 — Hold samples at a declared temperature, and optionally a declared atmosphere, for a declared duration. The achieved temperature and duration are reported in the output and receipt. Kinds lab.incubator. Effects energy.heating, sample.state_change. Hazards thermal_burn, sample_loss, biohazard. Tags incubate, temperature hold, cell culture, thermal protocol, environmental control. Units actual_duration_s: s, actual_temperature: Cel, atmosphere.co2_percent: %, duration_s: s, temperature: Cel. Class limits {"temperature":{"max":80,"min":0,"reason":"incubator safe operating range; bindings narrow it","unit":"Cel"}}. Constraints cancellable true, max_duration_ms 86400000. Input {"additionalProperties":false,"properties":{"atmosphere":{"additionalProperties":false,"properties":{"co2_percent":{"maximum":100,"minimum":0,"type":"number","x-mhs-unit":"%"}},"type":"object"},"duration_s":{"minimum":0,"type":"number","x-mhs-unit":"s"},"sample_ids":{"items":{"maxLength":128,"type":"string"},"maxItems":384,"minItems":1,"type":"array"},"temperature":{"type":"number","x-mhs-unit":"Cel"}},"required":["sample_ids","temperature","duration_s"],"type":"object"} · Output {"additionalProperties":false,"properties":{"actual_duration_s":{"minimum":0,"type":"number","x-mhs-unit":"s"},"actual_temperature":{"type":"number","x-mhs-unit":"Cel"},"incubated":{"type":"boolean"}},"required":["incubated","actual_temperature"],"type":"object"}

cap.sample.centrifuge.v1 — Centrifuge samples

invoke · R2 · determinism none · exclusive · modes hardware, simulated, hybrid · since 0.9.0 · requires permit — Spin declared samples at a target speed for a declared duration, optionally at a controlled temperature, then report the achieved speed and duration. Kinds lab.centrifuge. Effects sample.state_change. Hazards centrifuge_imbalance, aerosol, sample_loss, rotor_failure. Tags centrifuge, spin, pellet, phase separation, rpm. Units duration_s: s, duration_s_actual: s, rpm: /min, rpm_actual: /min, temperature: Cel. Class limits {"rpm":{"max":15000,"min":0,"reason":"rotor and sample balance limits are declared per binding","unit":"/min"}}. Constraints cancellable false, max_duration_ms 7200000. Notes: Cancellation is not offered while spinning: stopping a centrifuge mid-run is itself a hazard. Use mhs.safety.estop for emergency stops. Input {"additionalProperties":false,"properties":{"duration_s":{"minimum":0,"type":"number","x-mhs-unit":"s"},"rpm":{"maximum":15000,"minimum":0,"type":"number","x-mhs-unit":"/min"},"sample_ids":{"items":{"maxLength":128,"type":"string"},"maxItems":384,"minItems":1,"type":"array"},"temperature":{"type":"number","x-mhs-unit":"Cel"}},"required":["sample_ids","rpm","duration_s"],"type":"object"} · Output {"additionalProperties":false,"properties":{"completed":{"type":"boolean"},"duration_s_actual":{"minimum":0,"type":"number","x-mhs-unit":"s"},"rpm_actual":{"minimum":0,"type":"number","x-mhs-unit":"/min"}},"required":["completed","rpm_actual"],"type":"object"}

cap.sample.seal.v1 — Seal a plate

invoke · R1 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 · status experimental — Apply a declared seal type to a microplate and report completion; the seal consumable is recorded as a consumable use. Kinds lab.plate_sealer. Effects consumable.use, material.move. Hazards thermal_burn, plate_damage. Tags seal plate, foil seal, adhesive seal, plate preparation, consumable. Constraints cancellable false, max_duration_ms 120000. Input {"additionalProperties":false,"properties":{"plate":{"additionalProperties":false,"properties":{"labware":{"maxLength":128,"type":"string"}},"required":["labware"],"type":"object"},"seal_type":{"enum":["foil","adhesive","heat","cap_mat"],"type":"string"}},"required":["plate","seal_type"],"type":"object"} · Output {"additionalProperties":false,"properties":{"seal_type":{"enum":["foil","adhesive","heat","cap_mat"],"type":"string"},"sealed":{"type":"boolean"}},"required":["sealed"],"type":"object"}

cap.sample.unseal.v1 — Unseal a plate

invoke · R1 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 · status experimental — Remove the seal from a microplate so that the wells are accessible, reporting completion. Kinds lab.plate_sealer. Effects material.move. Hazards plate_damage, cross_contamination, aerosol. Tags unseal, remove seal, peel, plate preparation, open plate. Constraints cancellable false, max_duration_ms 120000. Input {"additionalProperties":false,"properties":{"plate":{"additionalProperties":false,"properties":{"labware":{"maxLength":128,"type":"string"}},"required":["labware"],"type":"object"}},"required":["plate"],"type":"object"} · Output {"additionalProperties":false,"properties":{"unsealed":{"type":"boolean"}},"required":["unsealed"],"type":"object"}

cap.sample.store.v1 — Store samples

invoke · R2 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 · status experimental — Place samples into a declared storage location at a declared temperature and record the storage location in the output so later retrieval is unambiguous. Kinds lab.storage, lab.sample. Effects material.move, sample.state_change. Hazards sample_loss, frost_damage, biohazard. Tags store, archive, cold storage, sample inventory, freezer. Units temperature: Cel. Constraints cancellable true, max_duration_ms 600000. Input {"additionalProperties":false,"properties":{"location":{"additionalProperties":false,"properties":{"slot":{"maxLength":64,"type":"string"},"system":{"maxLength":64,"type":"string"}},"required":["system","slot"],"type":"object"},"sample_ids":{"items":{"maxLength":128,"type":"string"},"maxItems":384,"minItems":1,"type":"array"},"temperature":{"type":"number","x-mhs-unit":"Cel"}},"required":["sample_ids","location"],"type":"object"} · Output {"additionalProperties":false,"properties":{"location":{"additionalProperties":false,"properties":{"slot":{"maxLength":64,"type":"string"},"system":{"maxLength":64,"type":"string"}},"type":"object"},"stored":{"type":"boolean"}},"required":["stored","location"],"type":"object"}

7.7 Imaging (3 classes)

cap.imaging.capture.v1 — Capture a microscope image

invoke · R0 · determinism statistical · exclusive · modes hardware, simulated, hybrid · since 0.9.0 — Acquire a microscope image of the current field of view for a declared channel, exposure, binning and region of interest, returning an image artifact. Kinds instrument.microscope. Effects measurement.capture. Hazards photobleaching, privacy. Tags microscope, imaging, fluorescence, brightfield, camera acquisition. Units exposure_ms: ms. Constraints cancellable false, max_duration_ms 120000. Input {"additionalProperties":false,"properties":{"binning":{"maximum":16,"minimum":1,"type":"integer"},"camera":{"maxLength":64,"type":"string"},"channel":{"maxLength":64,"type":"string"},"exposure_ms":{"maximum":600000,"minimum":0,"type":"number","x-mhs-unit":"ms"},"roi":{"additionalProperties":false,"properties":{"height":{"minimum":1,"type":"integer"},"width":{"minimum":1,"type":"integer"},"x":{"minimum":0,"type":"integer"},"y":{"minimum":0,"type":"integer"}},"required":["x","y","width","height"],"type":"object"},"save_as":{"maxLength":128,"type":"string"}},"type":"object"} · Output {"additionalProperties":false,"properties":{"channel":{"maxLength":64,"type":"string"},"exposure_ms":{"minimum":0,"type":"number","x-mhs-unit":"ms"},"height":{"minimum":1,"type":"integer"},"image_ref":{"type":"string"},"width":{"minimum":1,"type":"integer"}},"required":["image_ref","width","height"],"type":"object"}

cap.imaging.focus.v1 — Focus the microscope

invoke · R1 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 — Move the focus axis to a target Z position or run an autofocus search over a declared range, returning the achieved Z position and focus score. Kinds instrument.microscope. Effects motion.cartesian. Hazards collision, slide_damage. Tags focus, autofocus, z stage, focal plane, sharpness. Units score: 1, search_range: um, target_z: um, z_um: um. Constraints cancellable true, max_duration_ms 120000. Input {"additionalProperties":false,"properties":{"method":{"enum":["autofocus","manual","none"],"type":"string"},"search_range":{"minimum":0,"type":"number","x-mhs-unit":"um"},"target_z":{"maximum":1000000,"minimum":-1000000,"type":"number","x-mhs-unit":"um"}},"required":["method"],"type":"object"} · Output {"additionalProperties":false,"properties":{"focused":{"type":"boolean"},"score":{"minimum":0,"type":"number","x-mhs-unit":"1"},"z_um":{"type":"number","x-mhs-unit":"um"}},"required":["focused","z_um"],"type":"object"}

cap.imaging.illumination.v1 — Set illumination

write · R1 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 — Set the illumination channel and intensity used for subsequent imaging or observation, with an optional bounded on-duration after which the light is turned off. Kinds instrument.microscope, light.source. Effects energy.emission, configuration.write. Hazards photobleaching, eye_exposure. Tags illumination, light source, led, fluorescence excitation, brightness. Units duration_ms: ms, intensity: %. Class limits {"intensity":{"max":100,"min":0,"reason":"emission power limits are declared per binding","unit":"%"}}. Constraints cancellable false, max_duration_ms 10000. Input {"additionalProperties":false,"properties":{"channel":{"maxLength":64,"type":"string"},"duration_ms":{"minimum":0,"type":"number","x-mhs-unit":"ms"},"intensity":{"maximum":100,"minimum":0,"type":"number","x-mhs-unit":"%"}},"required":["channel","intensity"],"type":"object"} · Output {"additionalProperties":false,"properties":{"applied":{"type":"boolean"},"channel":{"maxLength":64,"type":"string"},"intensity":{"type":"number","x-mhs-unit":"%"}},"required":["applied"],"type":"object"}

7.8 Optics (3 classes)

cap.optics.set_power.v1 — Set optical output power

write · R2 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 · status experimental · requires permit — Set the emitted optical power of a laser or light source to a declared setpoint, optionally ramping over a declared duration. Bindings for class 3B+ sources raise the risk class to R3. Kinds optics.laser, optics.source. Effects energy.emission, configuration.write. Hazards laser_radiation, eye_exposure, burns. Tags laser power, optical power, excitation, setpoint, emission control. Units power: mW, ramp_ms: ms, set_power_mw: mW. Class limits {"power":{"max":1000,"min":0,"reason":"class-dependent maximum emission; the binding MUST narrow this","unit":"mW"}}. Constraints cancellable false, max_duration_ms 30000. Notes: Requires a permit for R2 and above on hardware. The permit is bound to the exact input_digest. Input {"additionalProperties":false,"properties":{"channel":{"maxLength":64,"type":"string"},"power":{"minimum":0,"type":"number","x-mhs-unit":"mW"},"ramp_ms":{"minimum":0,"type":"number","x-mhs-unit":"ms"}},"required":["power"],"type":"object"} · Output {"additionalProperties":false,"properties":{"channel":{"maxLength":64,"type":"string"},"ramped":{"type":"boolean"},"set_power_mw":{"minimum":0,"type":"number","x-mhs-unit":"mW"}},"required":["set_power_mw"],"type":"object"}

cap.optics.shutter.v1 — Open or close an optical shutter

invoke · R2 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 · status experimental — Open or close a mechanical or electronic shutter in the optical path, reporting the resulting state and, for an open shutter, the open duration. Kinds optics.shutter. Effects energy.emission. Hazards laser_radiation, eye_exposure. Tags shutter, beam block, optical path, exposure control, safety shutter. Units open_duration_ms: ms. Constraints cancellable false, max_duration_ms 5000. Notes: Closing a shutter is the declared safe state for optical sources; it MUST NOT require a permit. Input {"additionalProperties":false,"properties":{"state":{"enum":["open","closed"],"type":"string"}},"required":["state"],"type":"object"} · Output {"additionalProperties":false,"properties":{"open_duration_ms":{"minimum":0,"type":"number","x-mhs-unit":"ms"},"state":{"enum":["open","closed"],"type":"string"}},"required":["state"],"type":"object"}

cap.optics.align.v1 — Align an optical element

invoke · R2 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 · status experimental · requires permit — Adjust an optical element along declared axes until a target coupling or position is reached, reporting the achieved offset and alignment quality. Kinds optics.stage, optics.mirror. Effects motion.cartesian, energy.emission. Hazards laser_radiation, eye_exposure, misalignment. Tags alignment, optical alignment, coupling, mirror adjustment, beam steering. Units offset_mm: mm, quality: 1, target: mm. Constraints cancellable true, max_duration_ms 600000. Input {"additionalProperties":false,"properties":{"axis":{"enum":["x","y","z","theta","phi"],"type":"string"},"method":{"enum":["hill_climb","manual","lookup"],"type":"string"},"target":{"type":"number","x-mhs-unit":"mm"}},"required":["axis","target"],"type":"object"} · Output {"additionalProperties":false,"properties":{"aligned":{"type":"boolean"},"offset_mm":{"type":"number","x-mhs-unit":"mm"},"quality":{"maximum":1,"minimum":0,"type":"number","x-mhs-unit":"1"}},"required":["aligned","offset_mm"],"type":"object"}

7.9 Measure (9 classes)

cap.measure.voltage.v1 — Measure voltage

read · R0 · determinism statistical · shared · modes hardware, simulated, hybrid, replay · since 0.9.0 — Measure a DC or RMS voltage on a declared channel or terminal pair and return the value with its sampling timestamp and measurement range. Kinds instrument.dmm, instrument.smu, sensor. Effects measurement.capture. Hazards high_voltage. Tags voltage, dmm, electrical measurement, potential difference, read channel. Units range_v: V, voltage: V. Constraints cancellable false, max_duration_ms 5000. Input {"additionalProperties":false,"properties":{"channel":{"maxLength":64,"type":"string"},"dc":{"type":"boolean"},"range_v":{"minimum":0,"type":"number","x-mhs-unit":"V"}},"type":"object"} · Output {"additionalProperties":false,"properties":{"range_v":{"minimum":0,"type":"number","x-mhs-unit":"V"},"sampled_at":{"type":"string"},"saturated":{"type":"boolean"},"voltage":{"type":"number","x-mhs-unit":"V"}},"required":["voltage","sampled_at"],"type":"object"}

cap.measure.current.v1 — Measure current

read · R0 · determinism statistical · shared · modes hardware, simulated, hybrid, replay · since 0.9.0 — Measure current on a declared channel and return the value with its timestamp and range. Kinds instrument.dmm, instrument.smu, sensor. Effects measurement.capture. Hazards high_voltage, overcurrent. Tags current, amperage, dmm, electrical measurement, read channel. Units current: A, range_a: A. Constraints cancellable false, max_duration_ms 5000. Input {"additionalProperties":false,"properties":{"channel":{"maxLength":64,"type":"string"},"range_a":{"minimum":0,"type":"number","x-mhs-unit":"A"}},"type":"object"} · Output {"additionalProperties":false,"properties":{"current":{"type":"number","x-mhs-unit":"A"},"range_a":{"minimum":0,"type":"number","x-mhs-unit":"A"},"sampled_at":{"type":"string"},"saturated":{"type":"boolean"}},"required":["current","sampled_at"],"type":"object"}

cap.measure.resistance.v1 — Measure resistance

read · R0 · determinism statistical · shared · modes hardware, simulated, hybrid, replay · since 0.9.0 — Measure resistance or impedance on a declared channel and return the value with its timestamp and excitation method. Kinds instrument.dmm, sensor. Effects measurement.capture. Hazards high_voltage. Tags resistance, ohmmeter, impedance, continuity, electrical measurement. Units resistance: Ohm. Constraints cancellable false, max_duration_ms 5000. Input {"additionalProperties":false,"properties":{"channel":{"maxLength":64,"type":"string"},"four_wire":{"type":"boolean"}},"type":"object"} · Output {"additionalProperties":false,"properties":{"four_wire":{"type":"boolean"},"resistance":{"minimum":0,"type":"number","x-mhs-unit":"Ohm"},"sampled_at":{"type":"string"}},"required":["resistance","sampled_at"],"type":"object"}

cap.measure.spectrum.v1 — Acquire a spectrum

invoke · R0 · determinism statistical · exclusive · modes hardware, simulated, hybrid, replay · since 0.9.0 — Acquire an optical or mass spectrum over a declared wavelength or mass range and return the axis and intensity arrays, or an artifact reference for large spectra. Kinds instrument.spectrometer, instrument.spectrophotometer. Effects measurement.capture. Hazards laser_radiation, sample_loss. Tags spectrum, spectroscopy, absorbance, wavelength scan, spectral acquisition. Units integration_ms: ms, intensities: 1, step_nm: nm, wavelength_max: nm, wavelength_min: nm, wavelengths: nm. Class limits {"wavelength_min":{"max":2500,"min":200,"reason":"detector range is declared per binding","unit":"nm"}}. Constraints cancellable true, max_duration_ms 300000. Input {"additionalProperties":false,"properties":{"artifact":{"type":"boolean"},"integration_ms":{"minimum":0,"type":"number","x-mhs-unit":"ms"},"step_nm":{"minimum":0.0001,"type":"number","x-mhs-unit":"nm"},"wavelength_max":{"minimum":0,"type":"number","x-mhs-unit":"nm"},"wavelength_min":{"minimum":200,"type":"number","x-mhs-unit":"nm"}},"required":["wavelength_min","wavelength_max"],"type":"object"} · Output {"additionalProperties":false,"properties":{"artifact_ref":{"type":"string"},"intensities":{"items":{"type":"number","x-mhs-unit":"1"},"type":"array"},"sampled_at":{"type":"string"},"wavelengths":{"items":{"type":"number","x-mhs-unit":"nm"},"type":"array"}},"required":["sampled_at"],"type":"object"}

cap.measure.intensity.v1 — Measure intensity

read · R0 · determinism statistical · shared · modes hardware, simulated, hybrid, replay · since 0.9.0 — Measure optical or radiant intensity at a declared wavelength or channel and return the value with its unit and integration time. Kinds instrument.spectrometer, sensor.optical. Effects measurement.capture. Hazards laser_radiation. Tags intensity, photometry, optical power, fluorescence intensity, detector count. Units integration_ms: ms, intensity: 1, wavelength_nm: nm. Constraints cancellable false, max_duration_ms 10000. Input {"additionalProperties":false,"properties":{"channel":{"maxLength":64,"type":"string"},"integration_ms":{"minimum":0,"type":"number","x-mhs-unit":"ms"},"wavelength_nm":{"minimum":0,"type":"number","x-mhs-unit":"nm"}},"type":"object"} · Output {"additionalProperties":false,"properties":{"integration_ms":{"minimum":0,"type":"number","x-mhs-unit":"ms"},"intensity":{"type":"number","x-mhs-unit":"1"},"sampled_at":{"type":"string"},"saturated":{"type":"boolean"}},"required":["intensity","sampled_at"],"type":"object"}

cap.measure.mass.v1 — Measure mass

read · R0 · determinism statistical · shared · modes hardware, simulated, hybrid, replay · since 0.9.0 — Measure the mass on a balance or load cell and report the value and stability flag. Kinds instrument.balance, sensor. Effects measurement.capture. Hazards sample_loss. Tags mass, weighing, balance, gravimetry, load cell. Units mass: mg. Constraints cancellable false, max_duration_ms 30000. Input {"additionalProperties":false,"properties":{"channel":{"maxLength":64,"type":"string"},"settle":{"type":"boolean"}},"type":"object"} · Output {"additionalProperties":false,"properties":{"mass":{"type":"number","x-mhs-unit":"mg"},"sampled_at":{"type":"string"},"stable":{"type":"boolean"}},"required":["mass","stable","sampled_at"],"type":"object"}

cap.measure.temperature.v1 — Measure temperature

read · R0 · determinism statistical · shared · modes hardware, simulated, hybrid, replay · since 0.9.0 — Measure temperature at a declared location and return the value with its timestamp and stability flag. Kinds instrument.thermometer, sensor.temperature, instrument.incubator. Effects measurement.capture. Hazards thermal_burn. Tags temperature, thermometer, thermal measurement, probe, sensor. Units temperature: Cel. Constraints cancellable false, max_duration_ms 5000. Input {"additionalProperties":false,"properties":{"location":{"maxLength":64,"type":"string"},"probe":{"maxLength":64,"type":"string"}},"type":"object"} · Output {"additionalProperties":false,"properties":{"sampled_at":{"type":"string"},"stable":{"type":"boolean"},"temperature":{"type":"number","x-mhs-unit":"Cel"}},"required":["temperature","sampled_at"],"type":"object"}

cap.measure.pressure.v1 — Measure pressure

read · R0 · determinism statistical · shared · modes hardware, simulated, hybrid, replay · since 0.9.0 — Measure absolute, gauge or differential pressure at a declared port and return the value with its reference and timestamp. Kinds sensor.pressure, instrument.gauge. Effects measurement.capture. Hazards pressure_hazard, chemical_exposure. Tags pressure, gauge, vacuum, baratron, process sensor. Units pressure: Pa. Constraints cancellable false, max_duration_ms 5000. Input {"additionalProperties":false,"properties":{"port":{"maxLength":64,"type":"string"},"reference":{"enum":["absolute","gauge","differential"],"type":"string"}},"required":["reference"],"type":"object"} · Output {"additionalProperties":false,"properties":{"pressure":{"type":"number","x-mhs-unit":"Pa"},"reference":{"enum":["absolute","gauge","differential"],"type":"string"},"sampled_at":{"type":"string"}},"required":["pressure","sampled_at"],"type":"object"}

cap.measure.flow.v1 — Measure flow

read · R0 · determinism statistical · shared · modes hardware, simulated, hybrid, replay · since 0.9.0 — Measure volumetric or mass flow at a declared line and optionally the accumulated volume since a declared instant. Kinds sensor.flow, instrument.flowmeter. Effects measurement.capture. Hazards pressure_hazard, spill. Tags flow, flow rate, flowmeter, liquid flow, gas flow. Units flow_rate: uL/s, total_volume: uL. Constraints cancellable false, max_duration_ms 5000. Input {"additionalProperties":false,"properties":{"line":{"maxLength":64,"type":"string"},"quantity":{"enum":["volume","mass"],"type":"string"}},"type":"object"} · Output {"additionalProperties":false,"properties":{"flow_rate":{"type":"number","x-mhs-unit":"uL/s"},"sampled_at":{"type":"string"},"total_volume":{"minimum":0,"type":"number","x-mhs-unit":"uL"}},"required":["flow_rate","sampled_at"],"type":"object"}

7.10 Thermal (1 class)

cap.thermal.setpoint.v1 — Set a thermal setpoint

write · R2 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 — Set the target temperature of a thermal zone and optionally wait for the zone to reach the setpoint within a declared tolerance. Kinds thermal.zone, instrument.incubator, lab.thermal_block. Effects energy.heating, energy.cooling, configuration.write. Hazards thermal_burn, sample_loss, overheating. Tags temperature control, setpoint, heater, thermal zone, ramp. Units actual_temperature: Cel, rate: K/min, setpoint: Cel, target_temperature: Cel, tolerance: K. Class limits {"target_temperature":{"max":300,"min":-50,"reason":"device thermal limits; bindings narrow them","unit":"Cel"}}. Constraints cancellable true, max_duration_ms 3600000. Input {"additionalProperties":false,"properties":{"rate":{"minimum":0,"type":"number","x-mhs-delta":true,"x-mhs-unit":"K/min"},"target_temperature":{"type":"number","x-mhs-unit":"Cel"},"tolerance":{"minimum":0,"type":"number","x-mhs-delta":true,"x-mhs-unit":"K"},"wait":{"type":"boolean"}},"required":["target_temperature"],"type":"object"} · Output {"additionalProperties":false,"properties":{"actual_temperature":{"type":"number","x-mhs-unit":"Cel"},"reached":{"type":"boolean"},"setpoint":{"type":"number","x-mhs-unit":"Cel"}},"required":["setpoint"],"type":"object"}

7.11 Actuation (3 classes)

cap.actuation.gpio.v1 — Drive a digital or analog output

write · R1 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 — Drive a general-purpose output pin to a declared digital or analog value, reporting the applied value. The pin's electrical limits are declared per binding. Kinds io.gpio, io.digital. Effects configuration.write. Hazards high_voltage, unexpected_actuation. Tags gpio, digital output, relay, trigger, analog output. Units value: 1. Constraints cancellable false, max_duration_ms 2000. Input {"additionalProperties":false,"properties":{"mode":{"enum":["digital","analog","pwm"],"type":"string"},"pin":{"minimum":0,"type":"integer"},"value":{"type":"number","x-mhs-unit":"1"}},"required":["pin","value"],"type":"object"} · Output {"additionalProperties":false,"properties":{"applied":{"type":"boolean"},"pin":{"minimum":0,"type":"integer"},"value":{"type":"number","x-mhs-unit":"1"}},"required":["pin","value","applied"],"type":"object"}

cap.actuation.valve.v1 — Set a valve position

write · R1 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 — Open, close or position a valve to a declared state, reporting the achieved position. The port routing map is declared per binding. Kinds actuation.valve, fluid.valve. Effects configuration.write, material.transfer. Hazards chemical_exposure, spill, overpressure. Tags valve, open valve, close valve, fluid routing, flow control. Units position: %. Constraints cancellable false, max_duration_ms 10000. Input {"additionalProperties":false,"properties":{"outlet":{"maxLength":64,"type":"string"},"position":{"maximum":100,"minimum":0,"type":"number","x-mhs-unit":"%"},"state":{"enum":["open","closed"],"type":"string"}},"type":"object"} · Output {"additionalProperties":false,"properties":{"position":{"maximum":100,"minimum":0,"type":"number","x-mhs-unit":"%"},"state":{"enum":["open","closed"],"type":"string"}},"required":["position"],"type":"object"}

cap.actuation.pump.v1 — Run a pump

invoke · R1 · determinism statistical · exclusive · modes hardware, simulated, hybrid · since 0.9.0 — Run a pump at a declared flow rate for a declared duration or volume in a declared direction, reporting the volume moved. Kinds actuation.pump, fluid.pump. Effects material.transfer, energy.emission. Hazards chemical_exposure, spill, overpressure. Tags pump, infuse, withdraw, flow control, dosing. Units dispensed_volume: uL, duration_s: s, flow_rate: uL/s, volume: uL. Class limits {"flow_rate":{"max":10000,"min":0,"reason":"pump and tubing limits are declared per binding","unit":"uL/s"}}. Constraints cancellable true, max_duration_ms 3600000. Input {"additionalProperties":false,"properties":{"direction":{"enum":["forward","reverse"],"type":"string"},"duration_s":{"minimum":0,"type":"number","x-mhs-unit":"s"},"flow_rate":{"minimum":0,"type":"number","x-mhs-unit":"uL/s"},"volume":{"minimum":0,"type":"number","x-mhs-unit":"uL"}},"required":["flow_rate","direction"],"type":"object"} · Output {"additionalProperties":false,"properties":{"dispensed_volume":{"minimum":0,"type":"number","x-mhs-unit":"uL"},"duration_s":{"minimum":0,"type":"number","x-mhs-unit":"s"}},"required":["dispensed_volume"],"type":"object"}

7.12 Compute (2 classes)

cap.compute.submit.v1 — Submit a bounded compute job

invoke · R1 · determinism none · serialized · modes hardware, simulated, hybrid · since 0.9.0 — Run a bounded command-line computation on the device host with a declared timeout and return exit code and stdout/stderr artifact references. Always R1 or higher. Kinds compute.node, host.process. Effects computation.execute. Hazards arbitrary_code, resource_exhaustion. Tags compute job, run command, analysis, script execution, bounded process. Units timeout_s: s. Constraints cancellable true, max_duration_ms 86400000. Notes: The endpoint MUST NOT accept shell metacharacter expansion; command is an argv vector. The binding MUST declare which executable allowlist applies. Input {"additionalProperties":false,"properties":{"command":{"items":{"maxLength":4096,"type":"string"},"maxItems":256,"minItems":1,"type":"array"},"cwd":{"maxLength":4096,"type":"string"},"env":{"additionalProperties":true,"properties":{},"type":"object","x-mhs-open":true},"input_refs":{"items":{"maxLength":512,"type":"string"},"maxItems":256,"type":"array"},"timeout_s":{"maximum":86400,"minimum":1,"type":"number","x-mhs-unit":"s"}},"required":["command","timeout_s"],"type":"object"} · Output {"additionalProperties":false,"properties":{"duration_ms":{"minimum":0,"type":"integer"},"exit_code":{"minimum":-256,"type":"integer"},"stderr_ref":{"type":"string"},"stdout_ref":{"type":"string"}},"required":["exit_code"],"type":"object"}

cap.compute.cancel.v1 — Cancel a compute job

invoke · R0 · determinism none · shared · modes hardware, simulated, hybrid · since 0.9.0 · status deprecated — Cancel a previously submitted compute job and report the signal used and whether the job terminated. Kinds compute.node, host.process. Effects computation.execute. Hazards resource_exhaustion. Tags cancel job, kill process, abort compute, interrupt, stop analysis. Units grace_s: s. Constraints cancellable false, max_duration_ms 60000. Replaced by mhs.operations.cancel. Notes: Deprecated in 0.9: Duplicate of the protocol method mhs.operations.cancel. The class stays valid and callable for its deprecation window; new drivers use the protocol method. Input {"additionalProperties":false,"properties":{"grace_s":{"maximum":300,"minimum":0,"type":"number","x-mhs-unit":"s"},"target_job_id":{"maxLength":128,"type":"string"}},"required":["target_job_id"],"type":"object"} · Output {"additionalProperties":false,"properties":{"cancelled":{"type":"boolean"},"signal":{"maxLength":32,"type":"string"}},"required":["cancelled"],"type":"object"}

7.13 Process (1 class)

cap.process.run.v1 — Run a process recipe

invoke · R2 · determinism none · exclusive · modes hardware, simulated, hybrid · since 0.9.0 — Execute a named, versioned process recipe on a process controller with declared parameters and return the exit status and a report artifact. Kinds process.controller. Effects computation.execute, configuration.write. Hazards sample_loss, thermal_burn, pressure_hazard. Tags process recipe, unit operation, batch process, recipe execution, process control. Constraints cancellable true, max_duration_ms 86400000. Notes: The recipe is content-addressed: recipe_ref MUST resolve to an immutable document whose digest is recorded in the receipt. Input {"additionalProperties":false,"properties":{"dry_run":{"type":"boolean"},"parameters":{"additionalProperties":true,"properties":{},"type":"object","x-mhs-open":true},"recipe_ref":{"maxLength":512,"type":"string"}},"required":["recipe_ref"],"type":"object"} · Output {"additionalProperties":false,"properties":{"exit_code":{"minimum":-256,"type":"integer"},"measurements":{"additionalProperties":true,"properties":{},"type":"object","x-mhs-open":true},"report_ref":{"type":"string"}},"required":["exit_code"],"type":"object"}

7.14 Device (4 classes)

cap.device.describe.v1 — Describe the device

read · R0 · determinism exact · shared · modes hardware, simulated, hybrid, replay · since 0.9.0 · status deprecated — Return the device's generated profile, identity, mode, capability list and the digest of its manifest, so an agent can re-orient without re-discovering the endpoint. Kinds device, world.sim, robot.arm, instrument. Effects measurement.capture. Hazards none. Tags device description, capabilities, self description, manifest, orientation. Constraints cancellable false, max_duration_ms 5000. Replaced by mhs.devices.get. Notes: Deprecated in 0.9: Duplicate of the protocol method mhs.devices.get (and the generated reference file). The class stays valid and callable for its deprecation window; new drivers use the protocol method. The manifest digest allows a host to detect that a device profile changed under it between sessions. Input {"additionalProperties":false,"properties":{"detail":{"enum":["summary","full"],"type":"string"}},"type":"object"} · Output {"additionalProperties":false,"properties":{"capabilities":{"items":{"type":"string"},"type":"array"},"device_id":{"type":"string"},"instance_id":{"type":"string"},"manifest_digest":{"pattern":"^sha256:[0-9a-f]{64}$","type":"string"},"mode":{"enum":["hardware","simulated","hybrid","replay"],"type":"string"},"profile":{"additionalProperties":true,"properties":{},"type":"object","x-mhs-open":true}},"required":["device_id","mode","manifest_digest","capabilities"],"type":"object"}

cap.device.calibrate.v1 — Calibrate the device

invoke · R1 · determinism none · exclusive · modes hardware, simulated, hybrid · since 0.9.0 · requires permit — Run the device's calibration procedure against a declared reference or standard and return a calibration artifact reference and validity window. Kinds robot.arm, instrument, sensor, optics.laser. Effects configuration.write. Hazards misalignment, sample_loss. Tags calibration, reference standard, zeroing, accuracy, metrology. Constraints cancellable true, max_duration_ms 3600000. Input {"additionalProperties":false,"properties":{"notes":{"maxLength":1000,"type":"string"},"standard_ref":{"maxLength":512,"type":"string"},"targets":{"items":{"maxLength":64,"type":"string"},"maxItems":64,"type":"array"}},"type":"object"} · Output {"additionalProperties":false,"properties":{"calibrated":{"type":"boolean"},"calibration_ref":{"type":"string"},"valid_until":{"type":"string"}},"required":["calibrated","calibration_ref"],"type":"object"}

cap.device.self_test.v1 — Run a device self-test

invoke · R1 · determinism none · exclusive · modes hardware, simulated, hybrid, replay · since 0.9.0 — Run the device's built-in self-test and return a pass/fail verdict with per-check results and a report artifact reference. Self-test does not certify safety. Kinds device, instrument, robot.arm. Effects computation.execute. Hazards unexpected_actuation. Tags self test, diagnostics, bist, health check, fault detection. Constraints cancellable false, max_duration_ms 600000. Notes: A passing self-test is evidence about the device's own checks, not an MHS safety certification. Input {"additionalProperties":false,"properties":{"level":{"enum":["basic","full"],"type":"string"}},"type":"object"} · Output {"additionalProperties":false,"properties":{"checks":{"items":{"additionalProperties":false,"properties":{"id":{"maxLength":64,"type":"string"},"status":{"enum":["pass","fail","skip","warn"],"type":"string"}},"required":["id","status"],"type":"object"},"type":"array"},"passed":{"type":"boolean"},"report_ref":{"type":"string"}},"required":["passed","checks"],"type":"object"}

cap.device.configure.v1 — Configure named device parameters

write · R1 · determinism exact · exclusive · modes hardware, simulated, hybrid · since 0.9.0 — Write one or more named parameters of a resource (setpoints, ranges, modes, gains) as a partial patch and report what was applied. The binding's effective input schema is derived from the writable properties of the bound resource's state_schema. Kinds *. Effects state.write. Hazards none. Tags configure, set parameter, write setting, named parameter, setpoint. Constraints cancellable false, max_duration_ms 30000. Notes: Served by mhs.resource.write: a write is routed to the cap.device.configure.v1 binding of the target resource and its receipt carries this class id. The effective input schema of a binding is the set of state_schema properties that are not readOnly; each keeps its type, x-mhs-unit and bounds, and binding limits are keyed by state paths. A patch key outside the state schema fails with MHS.RESOURCE.FIELD_UNKNOWN; a readOnly key with MHS.RESOURCE.NOT_WRITABLE. resource_kinds '*' means any resource kind the device declares. The class floor is R1; a binding raises the risk to that of its most hazardous parameter. Input {"additionalProperties":true,"minProperties":1,"properties":{},"type":"object","x-mhs-open":true} · Output {"additionalProperties":false,"properties":{"applied":{"additionalProperties":true,"description":"The parameters as applied, keyed like the patch (values after any device rounding).","properties":{},"type":"object","x-mhs-open":true},"revision":{"minimum":0,"type":"integer"}},"required":["applied","revision"],"type":"object"}

<!-- END GENERATED: catalogue -->

CAP-033. Every endpoint claiming CL1 or above MUST bind at least one class from this catalogue or from a registered extension namespace, and MUST serve the class document via mhs.schema.get for every class it binds.

CAP-034. The classes in this section are the REQUIRED vocabulary of OpenMHS 0.9 in the sense that hosts and bridges MUST understand them; they are not all required to be implemented by every device. A device binds the subset it can honestly support.

8. Extension namespaces

CAP-035. A class that is not in this catalogue MUST live in an extension namespace: cap.x.<vendor>.<class>.v1 for a vendor-domain class published in the MHS registry, or x-cap.<vendor>.<class>.v1 for a private class that is not published. <vendor> MUST be a stable lowercase DNS-derived token (for example acme, pku-yuangroup).

CAP-036. An extension class MUST NOT redefine, shadow, or re-version a core class path. cap.x.acme.fluid.aspirate.v1 is allowed; cap.fluid.aspirate.v2 by a vendor is not.

CAP-037. A device manifest that binds an extension class MUST include the class document's digest in the binding (x-mhs-schema-digest, sha256:…) so hosts can pin the contract they reviewed.

CAP-038. Private x-cap.* classes MUST NOT appear in a registry claim or a conformance report as evidence of core conformance. They MAY appear in the device manifest with a notes statement that the class is vendor-specific.

CAP-039. Extension classes are subject to the same schema, unit, safety and lifecycle rules as core classes. "Extension" is a namespace statement, not a weaker contract.

9. Deprecation

CAP-040. Deprecation is announced by setting status: "deprecated", naming the replacement in supersedes on the replacement (or x-mhs-replaced-by on the deprecated document), and publishing the deprecation in the registry with a deprecated_at date and a removal date no earlier than the window in MHS-010 §5.

CAP-041. During the window, endpoints MUST keep serving the deprecated class document and MUST keep accepting it; hosts SHOULD warn the operator and SHOULD prefer the replacement when both are bound.

CAP-042. A class MUST NOT be removed from the core registry while any published conformance claim at CL2 or above names it. Removal requires either the window to expire or every claim to be re-issued against the replacement.

10. Generated artifacts and their consumers

ArtifactLocationConsumer
Class catalogue (data)capabilities.jsonWebsite capability browser, registry capability mapping, SDK tool descriptions.
Class catalogue (table)MHS-AHuman review, diffing, citation.
Class schema documentsthe input_schema and output_schema of each entry of capabilities.json, served by mhs.schema.get for a capability idmhs.schema.get, generated code APIs, MCP tool schemas.
Registry capability indexMHS/registry/capabilities.json (registry pipeline)Search by class, coverage statistics.

CAP-043. The catalogue JSON and this document MUST be regenerated in the same commit. CI MUST fail if capabilities.json does not byte-match the generator output (canonical JSON) or if MHS-A does not match the table generated from it.

CAP-044. The units map in capabilities.json MUST equal the set of x-mhs-unit annotations discovered in input_schema and output_schema, keyed by field path (dotted for nested objects, for example position.x; array-valued fields use the field name). If two different units share a path inside one class, the class is invalid.

11. Requirements traceability

Conformance test IDs equal requirement IDs (MHS-001 §4). The test areas relevant to this chapter are CAP (class documents and bindings) and REG (catalogue publication). The tests that MUST exist in the suite:

RequirementTestWhat it checks
CAP-004CAP-004Top-level input/output schemas are closed; x-mhs-open absent on core classes.
CAP-008CAP-008Every class served by mhs.schema.get validates against capability.schema.json.
CAP-016CAP-016A binding cannot accept an input that the class rejects (probe with an invalid value).
CAP-017CAP-017Device safety.risk_class ≥ max binding risk class.
CAP-021CAP-021Every numeric physical field carries x-mhs-unit; validator flags a stripped unit.
CAP-033CAP-033Every bound class is retrievable via mhs.schema.get.
CAP-034CAP-034All bound class ids match the core catalogue or a registered extension.
CAP-043CAP-043capabilities.json digest matches the published catalogue digest in hello.features / registry claim.

12. Informative: choosing between classes

This section is informative.

  • If the native call moves a robot to a joint configuration, use cap.motion.joint_position.v1; do not invent cap.motion.move.v1.
  • If the native call transfers material between containers, use cap.fluid.transfer.v1 (fluid) or material.move in cap.sample.move.v1 (labware/sample object), depending on what actually moves.
  • If the native call executes a user-supplied command line, use cap.process.run.v1 or cap.compute.submit.v1 and declare R1+ risk; never map an arbitrary shell to a read class.
  • If the native call only reports a value and has no side effect, use a read class. "It warms up the sensor" is a side effect.
  • If a class is missing, prefer an extension class over overloading a core class with a different meaning. Overloading is how device vocabularies rot.