# 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:

```python
from missioncore_plugin_sdk import v0alpha2 as sdk

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

For an isolated editable install:

```bash
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.