feat(plugin-sdk): add executable v0alpha2 contracts
This commit is contained in:
DCCONSTRUCTIONS
@@ -1,29 +1,53 @@
|
||||
# Mission Core Plugin SDK
|
||||
|
||||
This directory owns the versioned host/plugin contract. The v1alpha frontend
|
||||
contract, validated registry, generic runtime envelope, and backend read-only
|
||||
catalog are implemented in-tree, but this is not yet a separately published
|
||||
SDK package.
|
||||
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.
|
||||
|
||||
The v1alpha1 contract currently validates one model per plugin, one reviewed
|
||||
`transitional-in-process` backend entrypoint, a required safe `state.read`
|
||||
action, and declared UI/action metadata. It establishes:
|
||||
`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:
|
||||
|
||||
- plugin manifest, version compatibility, firmware profiles, and declarative
|
||||
permissions;
|
||||
- discovery candidates and opaque device references;
|
||||
- provisioning requests using secret references;
|
||||
- device-session lifecycle and health;
|
||||
- EvidenceStore handles and raw-artifact lineage;
|
||||
- canonical PointCloud, Pose, DeviceStatus, and metrics envelopes;
|
||||
- SceneSink and event interfaces;
|
||||
- capability-driven UI contribution data without plugin-owned layout.
|
||||
```python
|
||||
from missioncore_plugin_sdk import v0alpha2 as sdk
|
||||
|
||||
The XGRIDS K1 extraction is the first real-device acceptance path. Synthetic
|
||||
multi-plugin composition tests verify that backend routing has no K1 identity or
|
||||
protocol assumption; static boundary tests enforce the same rule in the frontend.
|
||||
request = sdk.OperationRequest.model_validate(document)
|
||||
schemas = sdk.contract_json_schemas()
|
||||
```
|
||||
|
||||
Current implementation references:
|
||||
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;
|
||||
@@ -31,13 +55,20 @@ Current implementation references:
|
||||
- `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 check between catalog and executable adapters;
|
||||
startup parity checks;
|
||||
- `docs/adr/0003-device-plugin-ui-and-runtime-boundary.md` — accepted boundary
|
||||
and extraction sequence.
|
||||
|
||||
The v1alpha lifecycle is fail-closed: inactive provider shells must perform no
|
||||
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 and independent device
|
||||
session IDs remain the next SDK milestone. `permissions`, `mutating`, and
|
||||
`secretFields` are contract metadata only in v1alpha1; host authorization and
|
||||
secret-vault enforcement are not implemented yet.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user