aab187937b
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.
91 lines
No EOL
3.1 KiB
Markdown
91 lines
No EOL
3.1 KiB
Markdown
# 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 |