NODEDC_MISSION_CORE/docs/domain-model/mission-core-experimental-vocabulary-v0alpha2.md

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.