lab-sync-driver-sdk 0.3.0__tar.gz

lab_sync_driver_sdk-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lab Sync
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lab_sync_driver_sdk-0.3.0/MANIFEST.in

@@ -0,0 +1,2 @@
+# The tests run from the repository; they are not part of the distribution.
+prune tests

lab_sync_driver_sdk-0.3.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: lab-sync-driver-sdk
+Version: 0.3.0
+Summary: Public driver-authoring SDK for the device engine: subclass Device, decorate commands, serve() over stdio
+Author: Lab Sync
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lab-sync-driver-protocol==0.3.0
+Provides-Extra: lab
+Requires-Dist: lab-device-sdk>=0.1.12; extra == "lab"
+Requires-Dist: fastapi>=0.110; extra == "lab"
+Requires-Dist: uvicorn>=0.30; extra == "lab"
+Dynamic: license-file
+
+# lab-sync-driver-sdk
+
+Write a lab device driver as a decorated Python class and serve it as a
+supervised child process. A driver subclasses `Device`, decorates async
+methods with `@command` and the typed in/out decorators, and calls
+`serve(device)` to speak the stdio wire protocol defined by
+[`lab-sync-driver-protocol`](https://pypi.org/project/lab-sync-driver-protocol/). The SDK depends on
+nothing but that package, so a driver ships with its own runtime and never
+imports the supervisor that launches it.
+
+```bash
+pip install lab-sync-driver-sdk
+```
+
+## A driver
+
+```python
+import asyncio
+
+from lab_sync_driver_sdk import Device, command, float_in, string_in, string_out, serve
+
+
+class Greeter(Device):
+    device_type_id = "acme-greeter"
+    manufacturer = "Acme"
+    model = "Greeter 1"
+
+    @command("Greet", "Say hello", default_sim_sec=1.0)
+    @string_in("Name", "who to greet", default="world", maps_to="name")
+    @float_in("Delay", "seconds to wait first", default=0.0, min_value=0.0, maps_to="delay")
+    @string_out("Greeting", "what was said")
+    async def greet(self, name: str = "world", delay: float = 0.0, progress=None) -> dict[str, object]:
+        await asyncio.sleep(delay)
+        if progress is not None:
+            await progress(1.0, "greeted")
+        return {"Greeting": f"Hello, {name}!"}
+
+
+if __name__ == "__main__":
+    asyncio.run(serve(Greeter()))
+```
+
+The decorators produce the driver's `describe` reply: its commands, their
+inputs and outputs, and any optional metadata the class declares (`category`,
+physical dimensions, `default_nests`, `configurations`, telemetry channels).
+A command returns a dict, and every key in it must be declared with an output
+decorator. An undeclared key fails the command with `OutputValidationError`.
+A command that takes a `progress` parameter is handed an async
+`progress(fraction, message)` reporter.
+
+Once `serve` starts, stdout carries protocol frames only. The host points
+`sys.stdout` at stderr, so a stray `print` lands on the log channel rather
+than corrupting a frame.
+
+## Testing a driver
+
+`lab_sync_driver_sdk.testing.run_command` runs one command in-process, applying the
+same output validation the host applies:
+
+```python
+from lab_sync_driver_sdk.testing import run_command
+
+result = await run_command(Greeter(), "Greet", {"name": "lab"})
+assert result == {"Greeting": "Hello, lab!"}
+```
+
+## Connection settings
+
+`@settings()` plus the typed input decorators declare the form an operator fills
+in. `connect` receives the saved values in one of two shapes:
+
+```python
+# The dict, keyed by display name, beside a carrier that holds the form.
+@settings()
+@string_in("Host", "device address", default="10.0.0.1")
+async def connection_settings(self) -> None: ...
+
+async def connect(self, settings: dict[str, Any] | None = None) -> None:
+    host = str((settings or {}).get("Host", "10.0.0.1"))
+
+# Or one parameter per setting, with @settings() on connect itself.
+@settings()
+@string_in("Host", "device address", default="10.0.0.1", maps_to="host")
+@int_in("Port", "device port", default=4321, maps_to="port")
+async def connect(self, host: str, port: int) -> None: ...
+```
+
+In the second shape the host binds each parameter by `maps_to` (else the
+display name). The value comes from the saved setting, else the declared
+default, else the signature's own default, and is coerced to the declared type,
+so `connect` receives an `int` even when the value was saved as text. A setting
+with no matching parameter, or a required parameter with no setting, fails the
+connect with a message naming it. See `lab_sync_driver_sdk.settings_binding`.
+
+## Hosting a lab-device-sdk driver
+
+`lab_sync_driver_sdk.lab_host` serves a driver written against
+[`lab-device-sdk`](https://pypi.org/project/lab-device-sdk/) over the same
+protocol, unchanged. It needs the `lab` extra, which also brings in FastAPI
+and uvicorn for drivers that serve HTTP routes of their own:
+
+```bash
+pip install "lab-sync-driver-sdk[lab]"
+```
+
+It hosts one device per process, so it has to be told which instance it is
+running. A driver manifest declares that with the supervisor's `{device_id}`
+token rather than a hardcoded id, which is what lets a site run several
+devices of the same type:
+
+```toml
+[launch]
+type = "command"
+command = ["python", "-m", "lab_sync_driver_sdk.lab_host",
+           "--device", "my_pkg.my_device:MyDevice",
+           "--device-id", "{device_id}"]
+```
+
+## License
+
+MIT

lab_sync_driver_sdk-0.3.0/README.md

@@ -0,0 +1,121 @@
+# lab-sync-driver-sdk
+
+Write a lab device driver as a decorated Python class and serve it as a
+supervised child process. A driver subclasses `Device`, decorates async
+methods with `@command` and the typed in/out decorators, and calls
+`serve(device)` to speak the stdio wire protocol defined by
+[`lab-sync-driver-protocol`](https://pypi.org/project/lab-sync-driver-protocol/). The SDK depends on
+nothing but that package, so a driver ships with its own runtime and never
+imports the supervisor that launches it.
+
+```bash
+pip install lab-sync-driver-sdk
+```
+
+## A driver
+
+```python
+import asyncio
+
+from lab_sync_driver_sdk import Device, command, float_in, string_in, string_out, serve
+
+
+class Greeter(Device):
+    device_type_id = "acme-greeter"
+    manufacturer = "Acme"
+    model = "Greeter 1"
+
+    @command("Greet", "Say hello", default_sim_sec=1.0)
+    @string_in("Name", "who to greet", default="world", maps_to="name")
+    @float_in("Delay", "seconds to wait first", default=0.0, min_value=0.0, maps_to="delay")
+    @string_out("Greeting", "what was said")
+    async def greet(self, name: str = "world", delay: float = 0.0, progress=None) -> dict[str, object]:
+        await asyncio.sleep(delay)
+        if progress is not None:
+            await progress(1.0, "greeted")
+        return {"Greeting": f"Hello, {name}!"}
+
+
+if __name__ == "__main__":
+    asyncio.run(serve(Greeter()))
+```
+
+The decorators produce the driver's `describe` reply: its commands, their
+inputs and outputs, and any optional metadata the class declares (`category`,
+physical dimensions, `default_nests`, `configurations`, telemetry channels).
+A command returns a dict, and every key in it must be declared with an output
+decorator. An undeclared key fails the command with `OutputValidationError`.
+A command that takes a `progress` parameter is handed an async
+`progress(fraction, message)` reporter.
+
+Once `serve` starts, stdout carries protocol frames only. The host points
+`sys.stdout` at stderr, so a stray `print` lands on the log channel rather
+than corrupting a frame.
+
+## Testing a driver
+
+`lab_sync_driver_sdk.testing.run_command` runs one command in-process, applying the
+same output validation the host applies:
+
+```python
+from lab_sync_driver_sdk.testing import run_command
+
+result = await run_command(Greeter(), "Greet", {"name": "lab"})
+assert result == {"Greeting": "Hello, lab!"}
+```
+
+## Connection settings
+
+`@settings()` plus the typed input decorators declare the form an operator fills
+in. `connect` receives the saved values in one of two shapes:
+
+```python
+# The dict, keyed by display name, beside a carrier that holds the form.
+@settings()
+@string_in("Host", "device address", default="10.0.0.1")
+async def connection_settings(self) -> None: ...
+
+async def connect(self, settings: dict[str, Any] | None = None) -> None:
+    host = str((settings or {}).get("Host", "10.0.0.1"))
+
+# Or one parameter per setting, with @settings() on connect itself.
+@settings()
+@string_in("Host", "device address", default="10.0.0.1", maps_to="host")
+@int_in("Port", "device port", default=4321, maps_to="port")
+async def connect(self, host: str, port: int) -> None: ...
+```
+
+In the second shape the host binds each parameter by `maps_to` (else the
+display name). The value comes from the saved setting, else the declared
+default, else the signature's own default, and is coerced to the declared type,
+so `connect` receives an `int` even when the value was saved as text. A setting
+with no matching parameter, or a required parameter with no setting, fails the
+connect with a message naming it. See `lab_sync_driver_sdk.settings_binding`.
+
+## Hosting a lab-device-sdk driver
+
+`lab_sync_driver_sdk.lab_host` serves a driver written against
+[`lab-device-sdk`](https://pypi.org/project/lab-device-sdk/) over the same
+protocol, unchanged. It needs the `lab` extra, which also brings in FastAPI
+and uvicorn for drivers that serve HTTP routes of their own:
+
+```bash
+pip install "lab-sync-driver-sdk[lab]"
+```
+
+It hosts one device per process, so it has to be told which instance it is
+running. A driver manifest declares that with the supervisor's `{device_id}`
+token rather than a hardcoded id, which is what lets a site run several
+devices of the same type:
+
+```toml
+[launch]
+type = "command"
+command = ["python", "-m", "lab_sync_driver_sdk.lab_host",
+           "--device", "my_pkg.my_device:MyDevice",
+           "--device-id", "{device_id}"]
+```
+
+## License
+
+MIT

lab_sync_driver_sdk-0.3.0/__init__.py

@@ -0,0 +1,43 @@
+"""lab-sync-driver-sdk: the driver-authoring SDK.
+
+A driver subclasses `Device`, decorates async methods with `@command` and the
+in/out decorators, and runs `serve(device)` (over stdio). It depends only on
+the shared wire contract (`lab_sync_driver_protocol`), never on the supervisor that
+launches the driver.
+"""
+
+from lab_sync_driver_sdk.decorators import OutputValidationError
+from lab_sync_driver_sdk.decorators import bool_in
+from lab_sync_driver_sdk.decorators import bool_out
+from lab_sync_driver_sdk.decorators import command
+from lab_sync_driver_sdk.decorators import float_in
+from lab_sync_driver_sdk.decorators import float_out
+from lab_sync_driver_sdk.decorators import int_in
+from lab_sync_driver_sdk.decorators import int_out
+from lab_sync_driver_sdk.decorators import settings
+from lab_sync_driver_sdk.decorators import string_in
+from lab_sync_driver_sdk.decorators import string_out
+from lab_sync_driver_sdk.decorators import telemetry
+from lab_sync_driver_sdk.device import Device
+from lab_sync_driver_sdk.device import DeviceCategory
+from lab_sync_driver_sdk.device import NestOffset
+from lab_sync_driver_sdk.host import serve
+
+__all__ = [
+    "Device",
+    "DeviceCategory",
+    "NestOffset",
+    "OutputValidationError",
+    "bool_in",
+    "bool_out",
+    "command",
+    "float_in",
+    "float_out",
+    "int_in",
+    "int_out",
+    "serve",
+    "settings",
+    "string_in",
+    "string_out",
+    "telemetry",
+]

lab_sync_driver_sdk-0.3.0/decorators.py

@@ -0,0 +1,349 @@
+"""Driver authoring decorators.
+
+A driver author annotates async methods on a `Device` subclass:
+
+    @command("Echo", "Echo the message")
+    @string_in("message", "text to echo")
+    @string_out("message", "echoed text")
+    async def echo(self, message: str = "") -> dict[str, object]:
+        return {"message": message}
+
+Decorators accumulate a CommandMeta on the function; the host runtime
+(`lab_sync_driver_sdk.host`) builds the Describe message from it and validates outputs.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from dataclasses import field
+from typing import Protocol
+from typing import TypeVar
+
+F = TypeVar("F", bound=Callable[..., object])
+
+# Wire type names (match the protocol ParamDescriptor.type and the SDK surface).
+TYPE_STRING = "string"
+TYPE_INT = "int"
+TYPE_FLOAT = "float"
+TYPE_BOOL = "bool"
+
+
+@dataclass
+class Param:
+    name: str
+    description: str
+    type: str
+    options: list[str] | None = None  # constrained-to-options choices, when the param is an enum
+    dynamic_options: bool = False  # options are computed by the driver at runtime (see describe-options)
+    maps_to: str | None = None
+    default: object = None
+    min_value: float | None = None
+    max_value: float | None = None
+    string_type: str | None = None
+    type_details: str | None = None
+    allow_empty: bool = False
+    group: str = ""
+
+
+@dataclass
+class CommandMeta:
+    name: str = ""
+    description: str = ""
+    inputs: list[Param] = field(default_factory=list[Param])
+    outputs: list[Param] = field(default_factory=list[Param])
+    exclusive: bool = True
+    concurrent: bool = False
+    category: str = ""  # display grouping in operator UIs; "" lands in the default group
+    operator_visible: bool = True  # hidden commands stay callable but are not listed for operators
+    default_sim_sec: float | None = None  # nominal duration, the UI's progress-bar estimate
+    # Workflow phase hint: setup/processing/teardown/maintenance/emergency, or
+    # storage_present/storage_receive/storage_store/storage_position/storage_inventory.
+    # "" is unset. See `command` for what each phase tells a scheduler.
+    operation_phase: str = ""
+    # The command simulates itself, so the host must not stand in for it by pacing
+    # out `default_sim_sec` and returning typed defaults.
+    handles_simulation: bool = False
+
+
+@dataclass
+class TelemetryMeta:
+    """Declaration of a sampler that runs only while somebody is watching.
+
+    A telemetry channel is the opposite of a command in every way that matters:
+    nobody asks for an individual reading, the frames are un-correlated (they
+    carry no request id), and a frame nobody wants should never be produced at
+    all. That last part is the reason this exists rather than a driver simply
+    publishing on a timer -- sampling usually costs a round trip on the same
+    link the device's real work goes over, so the supervisor tells the driver when to
+    start and stop, and the default is stopped.
+    """
+
+    channel: str = ""
+    hz: float = 5.0
+    description: str = ""
+
+
+_ATTR = "__studio_command__"
+_SETTINGS_ATTR = "__studio_settings__"
+_TELEMETRY_ATTR = "__studio_telemetry__"
+
+
+def _meta(fn: object) -> CommandMeta:
+    meta = getattr(fn, _ATTR, None)
+    if not isinstance(meta, CommandMeta):
+        meta = CommandMeta()
+        setattr(fn, _ATTR, meta)
+    return meta
+
+
+def get_command_meta(fn: object) -> CommandMeta | None:
+    meta = getattr(fn, _ATTR, None)
+    return meta if isinstance(meta, CommandMeta) else None
+
+
+def command(  # noqa: PLR0913 - the decorator surface is the API; each field is a distinct declaration
+    name: str,
+    description: str = "",
+    *,
+    exclusive: bool = True,
+    concurrent: bool = False,
+    category: str = "",
+    operator_visible: bool = True,
+    default_sim_sec: float | None = None,
+    operation_phase: str = "",
+    handles_simulation: bool = False,
+) -> Callable[[F], F]:
+    """Declare a command.
+
+    `exclusive` means it needs the device to itself: the supervisor admits it only when no other
+    exclusive command is in flight there, so hardware expecting one command at a time is not
+    driven twice at once. Clear it for a command that guards no physical resource.
+
+    `concurrent` allows several invocations of this same command at once, which a stateless
+    service device needs when every running sequence routes its steps through one instance.
+
+    `operation_phase` is a workflow phase hint — setup/processing/teardown/maintenance/emergency,
+    plus the storage phases for a storage device that acts on a plate's way in or out itself.
+    Leave it unset unless it is true: a scheduler treats every `processing` command as a step a
+    plate can be sent to, so marking a command that does not process a plate offers a
+    misleading step. A scheduler does not offer the storage phases as steps; it runs them
+    itself when a plate leaves or enters storage, each at a fixed point around the robot's pick
+    or place:
+
+    - `storage_present` fetches a plate onto the device's *own* nest, **before** the robot
+      picks it on a get.
+    - `storage_receive` gets the device ready to take a plate, **before** the robot places it
+      on a put — a stacker raising its stack so a plate set into its ring lands on top. Put
+      side only: it never runs before a get.
+    - `storage_store` files a plate away off the device's nest, **after** the robot placed it
+      on a put.
+    - `storage_position` moves the storage to the robot (a carousel turning a hotel round),
+      first on **both** sides.
+    - `storage_inventory` reports which barcode is in each location the supervisor asks about.
+
+    A put therefore runs `storage_position` -> `storage_receive` -> the robot ->
+    `storage_store`, skipping whichever the device does not declare. Pick by *when* the device
+    has to act: a command that must run before the robot lets go of the plate is
+    `storage_receive`, never `storage_store`.
+
+    `handles_simulation` says the command does its own simulation. Leave it clear and the host
+    stands in for a simulated device by pacing out `default_sim_sec` and returning typed
+    defaults; set it and the command body runs even in simulation.
+    """
+
+    def deco(fn: F) -> F:
+        meta = _meta(fn)
+        meta.name = name
+        meta.description = description
+        meta.exclusive = exclusive
+        meta.concurrent = concurrent
+        meta.category = category
+        meta.operator_visible = operator_visible
+        meta.default_sim_sec = default_sim_sec
+        meta.operation_phase = operation_phase
+        meta.handles_simulation = handles_simulation
+        return fn
+
+    return deco
+
+
+def get_telemetry_meta(fn: object) -> TelemetryMeta | None:
+    """The telemetry declaration on a method, or None if it has none."""
+    meta = getattr(fn, _TELEMETRY_ATTR, None)
+    return meta if isinstance(meta, TelemetryMeta) else None
+
+
+def telemetry(channel: str, *, hz: float = 5.0, description: str = "") -> Callable[[F], F]:
+    """Declare a demand-gated sampler.
+
+    The decorated method takes no arguments and returns a JSON-serializable
+    mapping -- one reading. The host calls it about `hz` times a second, but
+    **only while the supervisor says someone is watching**, and never before then: a
+    driver that is connected but unobserved samples nothing.
+
+    That gating is the whole point. Reading a robot's joint angles means a round
+    trip on the serial link its motion commands share, so doing it for a page
+    nobody has open would steal bandwidth from the hardware. The supervisor
+    switches a channel on only while something downstream is subscribed to it,
+    so the thing that switches the sampler on is the thing that wants the data.
+
+    `hz` is a ceiling and a target, not a guarantee: a sampler that takes longer
+    than its period simply runs less often, and one that raises is logged and
+    retried on the next tick rather than tearing the channel down. Neither a
+    slow device nor a flaky read should end the stream.
+
+        @telemetry("articulation", hz=10)
+        async def sample_joints(self) -> dict[str, object]:
+            return {"joints": dict(zip(JOINT_IDS, await self.read_joints()))}
+
+    Args:
+        channel: Channel name, unique on the device. The supervisor publishes
+            its readings under this name.
+        hz: How often to sample while demand is on.
+        description: What the channel carries, for humans reading a describe.
+    """
+
+    def deco(fn: F) -> F:
+        setattr(fn, _TELEMETRY_ATTR, TelemetryMeta(channel=channel, hz=hz, description=description))
+        return fn
+
+    return deco
+
+
+def settings() -> Callable[[F], F]:
+    """Declare the device's connection settings on a method (conventionally `connect`).
+
+    The input decorators stacked under this one describe the settings form the operator fills in; the host reports them in describe and passes
+    the saved values dict into `connect(settings)`. Decorate `connect` itself with one parameter per setting (named by `maps_to`, else the
+    display name) and the host binds and coerces them instead -- see `lab_sync_driver_sdk.settings_binding`. A settings method is not a command.
+    """
+
+    def deco(fn: F) -> F:
+        setattr(fn, _SETTINGS_ATTR, True)
+        return fn
+
+    return deco
+
+
+def is_settings_method(fn: object) -> bool:
+    return bool(getattr(fn, _SETTINGS_ATTR, False))
+
+
+class _InputFactory(Protocol):
+    def __call__(  # noqa: PLR0913 - mirrors the input-decorator surface
+        self,
+        name: str,
+        description: str = "",
+        *,
+        default: object = None,
+        maps_to: str | None = None,
+        min_value: float | None = None,
+        max_value: float | None = None,
+        options: list[str] | None = None,
+        dynamic_options: bool = False,
+        string_type: str | None = None,
+        type_details: str | None = None,
+        allow_empty: bool = False,
+        group: str = "",
+    ) -> Callable[[F], F]: ...
+
+
+def _input(type_name: str) -> _InputFactory:
+    # insert(0) so that, since decorators apply bottom-up, source order is kept.
+    def make(  # noqa: PLR0913 - the decorator surface is the API; each field is a distinct declaration
+        name: str,
+        description: str = "",
+        *,
+        default: object = None,
+        maps_to: str | None = None,
+        min_value: float | None = None,
+        max_value: float | None = None,
+        options: list[str] | None = None,
+        dynamic_options: bool = False,
+        string_type: str | None = None,
+        type_details: str | None = None,
+        allow_empty: bool = False,
+        group: str = "",
+    ) -> Callable[[F], F]:
+        def deco(fn: F) -> F:
+            _meta(fn).inputs.insert(
+                0,
+                Param(
+                    name,
+                    description,
+                    type_name,
+                    options=options,
+                    dynamic_options=dynamic_options,
+                    maps_to=maps_to,
+                    default=default,
+                    min_value=min_value,
+                    max_value=max_value,
+                    string_type=string_type,
+                    type_details=type_details,
+                    allow_empty=allow_empty,
+                    group=group,
+                ),
+            )
+            return fn
+
+        return deco
+
+    return make
+
+
+def _output(type_name: str) -> Callable[[str, str], Callable[[F], F]]:
+    def make(name: str, description: str = "") -> Callable[[F], F]:
+        def deco(fn: F) -> F:
+            _meta(fn).outputs.insert(0, Param(name, description, type_name))
+            return fn
+
+        return deco
+
+    return make
+
+
+string_in = _input(TYPE_STRING)
+int_in = _input(TYPE_INT)
+float_in = _input(TYPE_FLOAT)
+bool_in = _input(TYPE_BOOL)
+
+string_out = _output(TYPE_STRING)
+int_out = _output(TYPE_INT)
+float_out = _output(TYPE_FLOAT)
+bool_out = _output(TYPE_BOOL)
+
+
+def param_dict(param: Param) -> dict[str, object]:
+    """Serialize a Param to its wire descriptor (describe inputs / settings entries)."""
+    descriptor: dict[str, object] = {"name": param.name, "description": param.description, "type": param.type}
+    optional: dict[str, object | None] = {
+        "options": param.options,
+        "maps_to": param.maps_to,
+        "default": param.default,
+        "min_value": param.min_value,
+        "max_value": param.max_value,
+        "string_type": param.string_type,
+        "type_details": param.type_details,
+    }
+    descriptor.update({key: value for key, value in optional.items() if value is not None})
+    if param.dynamic_options:
+        descriptor["dynamic_options"] = True
+    if param.allow_empty:
+        descriptor["allow_empty"] = True
+    if param.group:
+        descriptor["group"] = param.group
+    return descriptor
+
+
+class OutputValidationError(Exception):
+    """A command returned fields not declared with an output decorator."""
+
+
+def validate_outputs(meta: CommandMeta, result: dict[str, object]) -> None:
+    """Raise `OutputValidationError` if the result has a field no output decorator declared."""
+    declared = {p.name for p in meta.outputs}
+    extra = set(result) - declared
+    if extra:
+        msg = f"command '{meta.name}' returned undeclared output fields: {sorted(extra)}"
+        raise OutputValidationError(msg)