# Hub Ecosystem Capability Bridge

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

---

## Purpose

Map reuse-surface capability IDs to State Hub catalog rows and Core Hub
`hub_capability_manifests` without inventing parallel naming schemes.

---

## Three representations

| Representation | Location | Identifier | Purpose |
| --- | --- | --- | --- |
| **Reuse-surface registry** | `registry/capabilities/*.md` + federation index | `capability.<domain>.<name>` | Discovery, maturity, consumer guidance |
| **State Hub catalog** | `capability_catalog` table | UUID row + `capability_type` + `title` | Dev workflow, requests, maturity tracking |
| **Core Hub manifest** | `hub_capability_manifests` table | UUID row + `body_json` | Inter-Hub `/api/v2` bootstrap, widget activation |

These are complementary, not duplicates of the same row.

---

## Worked example: hub stack capabilities

### `capability.infotech.hub-core-library`

| Field | Value |
| --- | --- |
| Registry owner | `hub-core` |
| State Hub catalog | Optional row with `capability_type=library`, linked to `hub-core` repo |
| Core Hub manifest | Not required — library is not a deployed hub |

### `capability.infotech.core-hub`

| Field | Value |
| --- | --- |
| Registry owner | `core-hub` |
| State Hub catalog | Row referencing `core-hub` managed repo |
| Core Hub manifest | Activated manifest for `hubSlug=core-hub` with widgets for ops evidence |

**Manifest `body_json` should include:**

```json
{
  "reuseSurfaceId": "capability.infotech.core-hub",
  "manifestVersion": "0.1.0",
  "capabilities": []
}
```

### `capability.statehub.workstream-coordinate` (if registered)

| Field | Value |
| --- | --- |
| Registry owner | `state-hub` |
| State Hub catalog | Native — describes the dev coordination service |
| Core Hub manifest | None — state-hub is not an Inter-Hub framework hub |

---

## Bridge rules

1. **Registry ID is the stable public name** — manifests and catalog rows reference it in JSON metadata.
2. **Catalog rows are dev-lane** — maturity, disputes, requests, WSJF triage live in State Hub.
3. **Manifests are ops-lane** — bootstrap, API consumers, widgets, interaction events live in Core Hub.
4. **Activation does not copy secrets** — API key material stays hash/prefix only in Core Hub.
5. **One reuse-surface ID per deployed hub** — ops-hub manifest references `capability.infotech.ops-hub` (when registered), not the core-hub library ID.

---

## Registration flow (recommended)

```text
1. Author capability.infotech.<name> in repo registry/
2. State Hub: register repo + optional capability_catalog row citing reuseSurfaceId
3. Core Hub: POST /api/v2/hub-capability-manifests with reuseSurfaceId in body
4. Core Hub: activate manifest → widgets → interaction-events for ops evidence
5. reuse-surface federation publish indexes maturity from registry files
```

---

## Anti-patterns

- Using `hub-core` manifest activation for a library that has no runtime widgets
- Creating a second capability ID in manifest JSON that disagrees with reuse-surface
- Storing full API keys in State Hub progress or catalog rows