# 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.