114 lines
3.2 KiB
Markdown
114 lines
3.2 KiB
Markdown
|
# 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
|