# Hub Ecosystem Event Mapping

**Updated:** 2026-07-09  
**Workplan:** `CUST-WP-0057-T06`

---

## Purpose

Clarify when to use State Hub `ProgressEvent` vs Core Hub `InteractionEvent`,
and how downstream consumers (activity-core, ops-hub) should interpret each.

---

## Event families

| Family | Owner | Table | Typical producer | Typical consumer |
| --- | --- | --- | --- | --- |
| **Progress** | state-hub | `progress_events` | Agents, consistency sync, custodian operators | State Hub MCP, dashboard, audit |
| **Interaction** | core-hub | `interaction_events` | ops-hub bootstrap, widget verification, operator CLI | activity-core sink, ops evidence |

Both are append-oriented and must not contain secrets.

---

## ProgressEvent (dev coordination)

**Schema owner:** `hub_core.models.progress_event` (library); State Hub extends with FKs.

**Emit when:**

- A workplan task status changes
- An agent logs session progress (`POST /progress/`)
- Consistency sync or reconciliation completes
- A custodian operator records a milestone

**Key fields:**

- `event_type` — e.g. `note`, `milestone`, `risk`, `alert`
- `summary` — human-readable one-liner
- `detail` — JSON payload (non-secret)
- `subject_refs` — generic JSON linking workplan_id, task_id, topic_id, repo_slug

**Example `subject_refs`:**

```json
{
  "workplan_id": "CUST-WP-0057",
  "task_id": "CUST-WP-0057-T01",
  "repo": "the-custodian"
}
```

---

## InteractionEvent (ops / framework evidence)

**Schema owner:** `core_hub.models.InteractionEvent`

**Emit when:**

- ops-hub bootstrap verifies an endpoint (`ops-endpoint-verified`)
- Operator CLI deployed smoke records widget activity
- A widget emits framework-scoped evidence under `/api/v2/interaction-events`

**Key fields:**

- `widget_id` — FK to core-hub `widgets`
- `event_type` — cataloged in `event-types` seed
- `view_context`, `metadata_json`, `body_json`

**Example body:**

```json
{
  "hubSlug": "ops-hub",
  "endpoint": "https://hub.coulomb.social/api/v2/hubs",
  "status": "verified"
}
```

---

## Mapping rules

| Situation | Use | Do not |
| --- | --- | --- |
| Agent closes a workplan task | `ProgressEvent` via State Hub | Duplicate as `InteractionEvent` |
| ops-hub bootstrap smoke passes | `InteractionEvent` via Core Hub | POST to State Hub progress |
| Cutover gate evaluation | `ProgressEvent` (custodian audit) + optional `InteractionEvent` (ops evidence) | Single combined table |
| activity-core ingestion | `core-hub-interaction-event` sink for interaction family | Assume progress events appear in Core Hub DB |

**Correlation:** When both families describe one operator action, use a shared
non-secret `correlation_id` in `detail` (progress) and `metadata_json`
(interaction). Do not dual-write the same semantic event to both tables.

---

## Consumer guidance

### activity-core

- Primary sink: Core Hub interaction events (`core-hub-interaction-event`)
- State Hub progress remains fallback during transition (see `testing-release-and-migration.md`)

### ops-hub

- Bootstrap and gate probes target Core Hub `/api/v2`
- Progress notes about bootstrap planning belong in State Hub

### Agents (MCP)

- Use State Hub `append_progress` for coordination work
- Do not call Core Hub interaction-event APIs unless executing ops-widget workflows