codex aab187937b

CI Smoke / host-smoke (push) Successful in 0s

Details

CI Smoke / container-smoke (push) Successful in 5s

Details

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.

2026-07-11 01:26:53 +02:00

3.2 KiB

Raw Permalink Blame History

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:

{
  "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:

{
  "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

3.2 KiB Raw Permalink Blame History