NODEDC_MISSION_CORE/packages/plugin-sdk

Mission Core Plugin SDK

This directory owns the versioned host/plugin contract. It is an independently installable in-tree package; it is not yet published to a package registry.

missioncore_plugin_sdk.v0alpha2 is the first executable backend-neutral contract layer. It uses closed, deeply immutable Pydantic models and exports JSON Schema for TypeScript, Rust, or other consumers. Nested mappings and collections are frozen after validation, and model_copy(update=...) is revalidated before a new contract is returned. Import the explicit version:

from missioncore_plugin_sdk import v0alpha2 as sdk

request = sdk.OperationRequest.model_validate(document)
schemas = sdk.contract_json_schemas()

For an isolated editable install:

uv pip install -e packages/plugin-sdk
python -m missioncore_plugin_sdk.v0alpha2 > plugin-sdk-v0alpha2.schema-bundle.json

Contract generations

The host accepts the original one-model v1alpha1 manifest and the additive v1alpha2 manifest. v1alpha2 permits one or more models, requires plugin-local compatibility-profile coverage for every model, and retains one reviewed transitional-in-process backend entrypoint plus a safe state.read action. The separate SDK v0alpha2 package establishes executable contracts for:

• stable and provisional device identities, transport aliases, and execution node bindings;
• independently revisioned enrollment, connectivity, and acquisition states;
• operation policy, request, acknowledgement, progress, completion, failure, timeout, cancellation, secret reference, and idempotency boundaries;
• canonical point cloud, pose, image, encoded video, and device-status streams;
• immutable evidence handles, raw transport records, lineage, and store protocol;
• firmware/profile compatibility assessments that fail closed before active device control;
• deterministic JSON Schema export for non-Python consumers.

The contracts deliberately contain no MQTT topic, BLE UUID, protobuf type, concrete viewer, or XGRIDS-specific field. Those belong to a plugin compatibility profile and adapter.

Current host implementation references:

• apps/control-station/src/core/device-plugins/ — TypeScript manifest and UI contribution contracts;
• apps/control-station/src/core/runtime/ — normalized runtime envelope;
• src/k1link/web/plugin_catalog.py — strict backend manifest validation;
• src/k1link/web/plugin_runtime.py — host-owned allowlisted action dispatcher;
• src/k1link/web/device_plugin_composition.py — manifest factory loader and startup parity checks;
• docs/adr/0003-device-plugin-ui-and-runtime-boundary.md — accepted boundary and extraction sequence.

The existing lifecycle is fail-closed: inactive provider shells perform no I/O, events are scoped by plugin ID, and selection cannot change until the active plugin confirms teardown. Process isolation remains a later host milestone. v0alpha2 models secret references and operation policy, but host authorization and the actual secret vault remain separate implementation responsibilities.

Version policy

v0alpha2 may receive additive fields while it remains experimental. A breaking wire or semantic change creates a new explicit module (for example v0alpha3); recorded documents keep their original api_version. Published field meanings and enum values are never silently redefined.