docs(ecosystem): complete hub stack consolidation (CUST-WP-0057)

Publish ecosystem architecture, event mapping, capability bridge, and async-base
decision docs; add cross-repo regression script; update extraction boundary and
bootstrap status; archive WP-0058 touch-ups.

docs/hub-ecosystem-event-mapping.md

@@ -0,0 +1,114 @@
+# 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