feat(plugins): add runtime handshake boundary
This commit is contained in:
@@ -2,8 +2,10 @@
|
||||
|
||||
This document maps the current repository to the target Mission Core
|
||||
architecture without claiming that deferred package and process boundaries
|
||||
already exist. The accepted device-lifecycle decision is recorded in
|
||||
[`ADR 0004`](adr/0004-plugin-sdk-v0alpha2-and-experimental-device-lifecycle.md).
|
||||
already exist. The device-lifecycle decision is recorded in
|
||||
[`ADR 0004`](adr/0004-plugin-sdk-v0alpha2-and-experimental-device-lifecycle.md),
|
||||
and the bounded laboratory runtime seam in
|
||||
[`ADR 0011`](adr/0011-laboratory-plugin-runtime-handshake-and-transport-seam.md).
|
||||
|
||||
## Current layout
|
||||
|
||||
@@ -14,7 +16,7 @@ already exist. The accepted device-lifecycle decision is recorded in
|
||||
| `packages/plugin-sdk/` | Installable v0alpha2 Pydantic contracts and JSON Schema export | Portable host/plugin identity, lifecycle, stream and evidence boundary |
|
||||
| `plugins/xgrids-k1/` | v1alpha2 manifest, exact profile/loader and plugin-owned React connection/acquisition UI | Independently versioned XGRIDS device plugin |
|
||||
| `plugins/xgrids-k1/frontend/` | XGRIDS provisioning, acquisition/replay, diagnostics, metrics, runtime mapping and scoped CSS | Plugin-owned reviewed frontend contribution |
|
||||
| `src/k1link/web/` | Local FastAPI host, plugin composition, in-memory operation/acquisition lifecycle and generic session API | Generic host APIs plus isolated plugin supervisor |
|
||||
| `src/k1link/web/` | Local FastAPI host, fail-closed runtime handshake/transport seam, in-memory operation/acquisition lifecycle and generic session API | Generic host APIs plus isolated plugin supervisor |
|
||||
| `src/k1link/device_plugins/xgrids_k1/` | Physically isolated K1 BLE/MQTT/protobuf/LZ4/camera/replay/CLI compatibility implementation | Independently built XGRIDS device plugin process |
|
||||
| `src/k1link/data_plane/` | Transport-neutral decoded in-process consumer views | Local projections hydrated from portable SDK envelopes |
|
||||
| `src/k1link/viewer/` | Vendor-neutral Rerun consumer, metrics and recorded blueprint | Replaceable canonical scene sink and presentation adapters |
|
||||
@@ -57,10 +59,14 @@ The Plugin SDK v0alpha2 separately defines model/device/session identity,
|
||||
operation events, acquisition-related session state, canonical stream
|
||||
envelopes, payload handles, evidence lineage and compatibility assessments. It
|
||||
is importable through the root editable path dependency and independently
|
||||
buildable from `packages/plugin-sdk`. Backend actions now instantiate immutable
|
||||
SDK `RuntimeActionInvocation` and `RuntimeActionResult` envelopes in the real
|
||||
dispatcher path. The live spatial path does not yet instantiate portable SDK
|
||||
stream envelopes or use the SDK `EvidenceStore` protocol.
|
||||
buildable from `packages/plugin-sdk`. A runtime-owned descriptor must match the
|
||||
manifest ID, version, host API and exact action set, then complete the
|
||||
`plugin-runtime/v0alpha1` handshake before its lifecycle health becomes ready.
|
||||
Backend actions instantiate immutable SDK `RuntimeActionInvocation` and
|
||||
`RuntimeActionResult` envelopes through the replaceable transport seam, and the
|
||||
host rejects uncorrelated results. The current transport is still in-process.
|
||||
The live spatial path does not yet instantiate portable SDK stream envelopes or
|
||||
use the SDK `EvidenceStore` protocol.
|
||||
|
||||
Frontend device workflows follow the same ownership rule. The generic host
|
||||
selects a manifest model and mounts its `device.connection` component. Concrete
|
||||
@@ -149,11 +155,14 @@ for the measured gate and remaining limits.
|
||||
## Remaining extraction order
|
||||
|
||||
Native replay parity, exact-profile physical point/pose regression, immutable
|
||||
SDK runtime-action envelopes and physical extraction of K1 transports/codecs are
|
||||
complete. Portable SDK stream/evidence envelopes remain separate from the
|
||||
allocation-conscious in-process preview views.
|
||||
SDK runtime-action envelopes, fail-closed runtime handshake and physical
|
||||
extraction of K1 transports/codecs are complete. Portable SDK stream/evidence
|
||||
envelopes remain separate from the allocation-conscious in-process preview
|
||||
views.
|
||||
|
||||
1. Add process isolation and a durable operation/evidence supervisor.
|
||||
1. When a real deployment or second execution target requires it, implement a
|
||||
subprocess transport behind the current seam, then add heartbeat timeout,
|
||||
restart policy and resource limits as separately accepted behavior.
|
||||
2. Replace compatibility routes and singleton state with multi-device session
|
||||
routing.
|
||||
3. Split Edge execution from the Control Station behind authenticated transport.
|
||||
@@ -163,6 +172,13 @@ allocation-conscious in-process preview views.
|
||||
plane; keep the modeling-command publisher disabled until its separate safety
|
||||
gate closes.
|
||||
|
||||
Complex equipment will likely be assembled from separately useful component
|
||||
plugins into configured hardware packs, while standalone equipment remains
|
||||
available for engineering work. That direction is intentionally not a current
|
||||
domain schema: pack ownership, roles, compatibility and lifecycle must be
|
||||
derived from real additional component families rather than inferred from the
|
||||
single K1 vertical.
|
||||
|
||||
## Invariants
|
||||
|
||||
- Raw bytes are appended and OS-flushed before preview work; aligned raw and
|
||||
@@ -208,6 +224,7 @@ From the repository root:
|
||||
uv sync --frozen --group dev
|
||||
uv run pytest \
|
||||
tests/test_plugin_sdk_v0alpha2_contracts.py \
|
||||
tests/test_plugin_runtime.py \
|
||||
tests/test_plugin_catalog.py \
|
||||
tests/test_xgrids_compatibility_profile.py \
|
||||
tests/test_device_lifecycle.py \
|
||||
|
||||
Reference in New Issue
Block a user