# Raft Warfighting Data Model (v1) Interoperability

`Object` and `Action` are Raft's first-class
warfighting types. They are independent of any other external
data model. Interop with external models is handled generically through
`ExternalReference`, so new integrations do not require new proto
fields.

This document explains how a system that currently operates off another model
can minimally translate into the WDM types with a thin adapter layer.

## The pattern

Every external record rides into the WDM through the same mechanism:

```proto
message ExternalReference {
  string type_url = 1;
  string external_id = 2;
  string source_system = 3;
  google.protobuf.Any payload = 4;
  google.protobuf.Timestamp captured_at = 5;
  string label = 6;
}
```

Three escalating levels of fidelity are available, depending on how
much the bridge layer does:

- **Level 1 (pointer only).** Populate `type_url`, `external_id`, and
  `source_system`. The actual external data model object lives in the source
  system's store; downstream consumers must fetch it themselves.
- **Level 2 (inline `Any`).** Additionally, pack the serialized data model object
  into `payload`. Consumers can decode it without a follow-up
  fetch, but native Object and Action consumers
  still have to reach into the `Any` to see anything useful.
- **Level 3 (bridge fields plus inline `Any`).** Level 2 plus a
  field-by-field copy of a handful of top-level fields so native
  consumers see a usable record without touching the `Any`. This is
  the recommended shape.

## Type URL convention

For protobuf payloads, use the standard `google.protobuf.Any` type URL
prefix, e.g. `type.googleapis.com/<full.type.name>`.

`source_system` should identify the producing system deployment with a
deployment-specific name.

## Things to know

- **Server-populated fields stay empty.** Leave them unset on the bridge path.
  The receiving platform fills them in.
- **Unwrapping on the consumer side.** Consumers that need full
  fidelity can walk `external_refs`, match on `type_url`, and
  `UnmarshalTo` the `payload` back into the original type.

## Suggested layout

A thin adapter package keeps bridge logic out of the warfighting
protos and isolates it for testing. Publishers call the adapter to
produce an `Object` or `Action` and hand the result to the
appropriate service. No changes to the warfighting protos are needed
to add a new bridge target; add another adapter package that wraps a
different external type into `ExternalReference` the same way.
