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

## Object understanding projection

Mission Core also has one bounded, executable perception vocabulary profile:
`missioncore.urban-object-semantics/v0`. It is referenced by the separate
`missioncore.object-understanding/v1` document and remains experimental. This
is a versioned projection over an existing `ObstacleObservation`; it is not a
second occupancy model, a long-term identity store, or a runtime ontology
service.

| Term | Meaning |
|---|---|
| `ObjectUnderstanding` | A source/frame-bound composition of immutable geometry, ranked semantic hypotheses, explicit semantic resolution, object state, advisory risk and evidence provenance. |
| `SemanticHypothesis` | One provider label mapped to a canonical class candidate with confidence, rank and evidence IDs. It is not class truth. |
| `SemanticDecision` | An explicit `unresolved`, `selected`, `ambiguous` or `conflict` result over the ranked hypotheses. |
| `ObjectStateEstimate` | Observed motion plus a separately qualified agency claim. A class prior is carried as a prior and never rewritten as observed motion. |
| `AdvisoryRiskAssessment` | Evidence-qualified risk level and suggested response for a future policy consumer. It never grants planner, navigation, safety or actuation authority. |
| `EvidenceProvenance` | The exact provider/model/revision/preprocess/prompt-set identity and source-frame binding supporting a claim. |

The v0 class profile is intentionally shallow. It covers the current named
consumers: human/adult/child, animal/dog, vehicle subtypes, passive wheeled
objects, common small static street obstacles, terrain discontinuities and
natural debris. Unknown and group-level classes remain valid outcomes; the
profile does not require a fragile leaf-class decision.

Mandatory object-perception non-conflation rules:

1. Occupancy identity is owned by `ObstacleObservation`, not by a semantic
   class, detector label or provider tracklet.
2. A missing or unresolved semantic class never means free space and never
   removes an occupied obstacle.
3. A raw provider label is not a canonical class; a ranked class hypothesis is
   not a selected class; a selected class is not independent truth.
4. Observed motion is not a class motion prior. In particular, a currently
   stationary vehicle may retain a self-propelled agency prior.
5. Semantic risk is advisory. `reduce-speed`, `yield`, `stop` and
   `route-around` values describe policy hints, not issued commands.
6. Vehicle-dependent traversability is not encoded as an intrinsic property
   of a curb, step, hemisphere or other obstacle class.
7. The class-free M4.8 obstacle-quality truth remains class-free. Semantic
   evaluation requires a separate sealed label generation and cannot rewrite
   an existing M4.8 result.

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