feat(plugins): add runtime handshake boundary

This commit is contained in:
DCCONSTRUCTIONS
2026-07-17 19:50:01 +03:00
parent 24a47318f2
commit 9d51080d2e
22 changed files with 856 additions and 138 deletions
+28 -11
View File
@@ -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 \