<!-- source-hash: f33597ddf2bdac88dfe784aaa957aacd -->
Defines the wire schema for inline entity references emitted by the chat backend and embedded within assistant message bodies.

## Key Components

### `ChatRef` Interface

The primary export — mirrors `ChatRef` from the multi-platform-hub server. Consumed by `<ChatMessageEnhanced renderEntityCard={...} />` to expand `[card://<type>:<id>]` markers in assistant responses into host-rendered JSX cards.

| Field | Type | Description |
|-------|------|-------------|
| `type` | `string` | Opaque document type from the host's RAG config (e.g. `'webinar'`, `'customer_interview'`) |
| `id` | `string` | Primary key — opaque string downstream |
| `title` | `string` | Display title used for fallback rendering when host renderer returns null |
| `url` | `string \| null` | Resolved external URL; null when no public link exists |
| `sourceRepo` | `string?` | `RagTableConfig.id` driving icon/label lookup; optional for backward-compat |
| `targetPlatform` | `string \| null \| undefined` | Platform owning the `url` destination — enables deterministic same-app vs. cross-app routing |
| `date` | `string?` | ISO date for the entity's canonical timestamp |
| `preview` | `string?` | PII-sanitized hover preview text |
| `metadata` | `Record<string, unknown>?` | Type-specific extras passed opaquely; used by `slack_message` refs to ship resolved `channelName`/`userName` |

## Usage Example

```typescript
// Host supplies a renderer; OSS-lib stays agnostic of entity types
const ref: ChatRef = {
  type: 'slack_message',
  sourceRepo: 'slack-messages',
  id: 'msg_abc123',
  title: 'Deployment discussion',
  url: 'https://myworkspace.slack.com/archives/C01/p123',
  targetPlatform: 'flamingo',
  date: '2024-11-01T14:30:00Z',
  preview: 'Discussed rollback strategy for v2.4...',
  metadata: { channelName: '#deployments', userName: 'alice' },
}

// Wire payload shape: refs map keyed by "<type>:<id>"
type RefsMap = Record<`${string}:${string}`, ChatRef>
```

> The OSS-lib has **no knowledge** of entity types or rendering logic. The host owns both the type vocabulary and the card renderer — `ChatRef` is purely a typed transport contract.