feat(plugin-sdk): add executable v0alpha2 contracts
This commit is contained in:
DCCONSTRUCTIONS
@@ -0,0 +1,108 @@
|
||||
# Mission Core experimental vocabulary v0alpha2
|
||||
|
||||
- Status: experimental, local to Mission Core and its Plugin SDK
|
||||
- Contract API: `missioncore.nodedc/plugin-sdk/v0alpha2`
|
||||
- Scope: laboratory device integration; not yet a NODE.DC platform ontology
|
||||
|
||||
This vocabulary fixes the meaning of the executable Plugin SDK contracts while
|
||||
their domain model is still being discovered. It is intentionally not loaded by
|
||||
Ontology Core. A term is promoted into the platform ontology only after its
|
||||
meaning is stable outside one device plugin, its owner and lifecycle are known,
|
||||
and migration from experimental captures is defined.
|
||||
|
||||
## Identity and lifecycle
|
||||
|
||||
| Term | Meaning |
|
||||
|---|---|
|
||||
| `DeviceModelRef` | A plugin-owned device model definition, not physical hardware. |
|
||||
| `DeviceInstanceRef` | A particular physical or logically enrolled device. Its ID may be stable or explicitly provisional. |
|
||||
| `TransportAlias` | An address observed in one scope, such as a BLE UUID assigned by one host or an IP address. It is not a stable identity. |
|
||||
| `DeviceSessionContext` | One bounded period in which one plugin adapter on one execution node communicates with one device instance. |
|
||||
| `ExecutionBinding` | The logical node and concrete agent process that owns a session. |
|
||||
| `Acquisition` | One bounded production of sensor data. It may span multiple canonical channels. |
|
||||
| `Operation` | One requested, auditable action with its own ID, deadline and terminal result. |
|
||||
|
||||
Enrollment, connectivity, and acquisition are independent state machines. A
|
||||
device can be enrolled while offline; it can be connected while acquisition is
|
||||
idle; and a failed acquisition does not erase device identity.
|
||||
|
||||
## Operations
|
||||
|
||||
An acknowledgement records receipt or admission of a request. It never proves
|
||||
that the requested physical action completed. Completion and failure are
|
||||
separate terminal events. Calibration, acquisition start, and acquisition stop
|
||||
therefore require an operation ID, explicit timeout, device/profile-specific
|
||||
acknowledgement evidence, progress when available, and exactly one terminal
|
||||
outcome.
|
||||
|
||||
Secret material is not a contract value. Operations carry only
|
||||
`SecretReference` objects; raw passwords, tokens, and credentials must not
|
||||
enter parameters, events, logs, browser storage, manifests, fixtures, or
|
||||
evidence metadata.
|
||||
|
||||
## Data and evidence
|
||||
|
||||
| Term | Meaning |
|
||||
|---|---|
|
||||
| `RawTransportRecord` | Immutable bytes and transport context observed before vendor decoding. |
|
||||
| `CanonicalStreamEnvelope` | Vendor-neutral data produced by a decoder, with device/session/acquisition lineage. |
|
||||
| `EvidenceHandle` | Content-addressed reference to immutable stored bytes. |
|
||||
| `EvidenceRecord` | Metadata, retention, redaction state and derivation lineage for one handle. |
|
||||
| `CompatibilityAssessment` | A point-in-time, evidence-backed decision about a device and compatibility profile. |
|
||||
|
||||
Decoding creates derived evidence or a canonical stream; it never overwrites
|
||||
the raw observation. A viewer is a consumer of canonical data and does not own
|
||||
device protocol, transport, identity, or command state.
|
||||
|
||||
## Mandatory non-conflation rules
|
||||
|
||||
1. `DeviceModelRef` is not `DeviceInstanceRef`.
|
||||
2. `DeviceInstanceRef` is not `DeviceSessionContext`.
|
||||
3. A host-local BLE UUID, IP address, SSID, MQTT client ID, or USB path is a
|
||||
`TransportAlias`, not a stable `device_id`.
|
||||
4. Enrollment state is not connectivity state; connectivity state is not
|
||||
acquisition state.
|
||||
5. An operation acknowledgement is not operation completion.
|
||||
6. A command published to a transport is not a successful physical action.
|
||||
7. K1 internal sensor calibration is not sensor-to-vehicle extrinsic
|
||||
calibration and is not geodetic calibration.
|
||||
8. Raw evidence is not a decoded frame; a decoded frame is not viewer state.
|
||||
9. Device time is not host time unless an explicit clock relationship has been
|
||||
measured and recorded.
|
||||
10. A camera preview is not assumed to be an independent raw camera stream.
|
||||
11. Compatibility with one firmware/profile is not compatibility with a model
|
||||
family or a future firmware.
|
||||
12. A plugin UI contribution is not ownership of Mission Core navigation,
|
||||
scene layout, persistence, or global application state.
|
||||
|
||||
## Deferred compatibility work
|
||||
|
||||
The following meanings are intentionally unresolved in v0alpha2. They must be
|
||||
defined and covered by migration tests before the portable contracts replace
|
||||
the transitional live path:
|
||||
|
||||
1. Canonical clock representation must distinguish UTC instants from native
|
||||
host/device monotonic ticks or nanoseconds and record the measured mapping
|
||||
between them. An aware datetime alone is not a monotonic timestamp.
|
||||
2. `ReferencedPayload` must define whether `byte_length` describes the complete
|
||||
referenced object or the selected segment, and how `offset` and
|
||||
`segment_length` participate in a frame's exact layout length.
|
||||
3. The coarse SDK `AcquisitionState` values require an explicit mapping to the
|
||||
richer transitional states such as `prepared`, `awaiting_external_start`,
|
||||
`acquiring`, `awaiting_external_stop`, `finalizing`, and `completed`.
|
||||
4. Generic manifest validation currently proves profile-link integrity, model
|
||||
coverage, path confinement, and profile identity. Evidence flags and
|
||||
device-specific semantics are validated by each plugin's fail-closed loader;
|
||||
they are not yet a generic compatibility-profile schema.
|
||||
|
||||
## Change and promotion policy
|
||||
|
||||
- Additive experimental changes remain in v0alpha2 only when an older document
|
||||
retains exactly the same meaning and remains valid.
|
||||
- Breaking shape or semantic changes create a new versioned contract module.
|
||||
- Deprecated fields and enum values remain readable until an explicit migration
|
||||
exists; they are never silently renamed or reused.
|
||||
- Raw captures retain their original contract/profile versions and hashes.
|
||||
- Promotion to Ontology Core requires at least one additional device family or
|
||||
a second platform service using the same meaning, an agreed owner, lifecycle,
|
||||
compatibility policy, and migration tests.
|
||||
Reference in New Issue
Block a user