inter-hub/contracts/extensions/hub-capability-manifest-v1.md

Hub Capability Manifest Contract

Name: hub-capability-manifest Version: 1.0 Date: 2026-03-31 Status: Active Layer: Extensions Maturity: Beta

---

Purpose

The Hub Capability Manifest is the formal extension registration mechanism of the IHF. It is the contract by which a domain hub (dev-hub, ops-hub, fin-hub, sec-hub) declares the vocabulary it introduces to the framework: widget types, event types, annotation categories, and policy scopes.

Without an active manifest, a domain hub is an unregistered participant. Its widgets and events are accepted by the framework, but its type vocabulary is not namespaced, not validated, and not discoverable in Phase 10's marketplace.

---

Schema

CREATE TABLE hub_capability_manifests (
    id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
    hub_id UUID NOT NULL UNIQUE REFERENCES hubs(id),
    manifest_version TEXT NOT NULL DEFAULT '1.0',
    declared_widget_types JSONB NOT NULL DEFAULT '[]',
    declared_event_types JSONB NOT NULL DEFAULT '[]',
    declared_annotation_categories JSONB NOT NULL DEFAULT '[]',
    declared_policy_scopes JSONB NOT NULL DEFAULT '[]',
    capability_description TEXT,
    contact TEXT,
    status TEXT NOT NULL DEFAULT 'draft',
    activated_at TIMESTAMP WITH TIME ZONE,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT now() NOT NULL,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT now() NOT NULL
);

---

Registration Workflow

1. Create manifest in draft
      ↓
2. Declare types (edit declared_* arrays)
      ↓
3. Activate (ActivateManifestAction)
      ↓  ← auto-registers declared types into their registries
4. Active manifest governs the hub's vocabulary

Step 1 — Create in draft

POST /HubCapabilityManifests/new?hubId=<hub-id>

One manifest per hub (UNIQUE constraint on hub_id). Creating a manifest for a hub that already has one (in any status) requires retiring the existing active manifest first.

Step 2 — Declare types

While in draft status, edit the declared_* JSONB arrays. Each array contains the string names of types the hub will own:

{
  "declared_widget_types": ["dev-pipeline-run", "dev-build-status"],
  "declared_event_types": ["dev-pipeline-started", "dev-pipeline-failed"],
  "declared_annotation_categories": ["dev-blocker", "dev-flaky-test"],
  "declared_policy_scopes": ["dev-internal"]
}

Naming convention: domain-owned types should be prefixed with the domain shortcode to prevent collisions (e.g. dev-, fin-, sec-, ops-). Framework-level types (no prefix) are owned by inter-hub and shared by all hubs.

Step 3 — Activate

POST /HubCapabilityManifests/ActivateManifest?hubCapabilityManifestId=<id>

On activation:

• For each name in declared_widget_types: insert into widget_type_registry with owner_hub_id = hub.id if not already present.
• Same for declared_event_types, declared_annotation_categories, declared_policy_scopes.
• If any declared name already exists in a registry with a different owner_hub_id, activation is rejected with a conflict error.
• If any declared name exists with owner_hub_id = NULL (framework-level), activation is rejected: framework types cannot be claimed by a domain hub.
• status is set to active, activated_at is set to now().

---

Invariants

1. Type names are permanent. Once a type name is registered (either via seed or manifest activation), it cannot be deleted from the registry — only deprecated. Other hubs may already depend on it.

2. Activated manifests are read-only on declared arrays. To add new types, retire the manifest and create a new draft, or use DraftAmendmentAction which creates an amended draft pending re-activation.

3. One active manifest per hub. The UNIQUE constraint on hub_id plus the activation workflow enforce this.

4. Framework types cannot be claimed. Type names with owner_hub_id = NULL are owned by the framework. A domain hub manifest that attempts to declare an existing framework type name is rejected.

---

Status Lifecycle

draft → active → retired
              ↓
           (superseded by a new draft → active cycle)

A retired manifest's types remain in the registry. If the hub is decommissioned, the types should be deprecated (not deleted) in the registry.

---

Failure Modes

Scenario	Behaviour
Duplicate type name (same hub)	Idempotent — skipped, not an error
Duplicate type name (different hub)	Activation rejected with conflict error
Framework type name claimed	Activation rejected
Edit of active manifest declared arrays	Rejected — manifest is read-only
Hub with no manifest creates hub-owned type	Warning in fitness function; types accepted but unmanifested

---

Implementation Reference

• Schema: Application/Schema.sql (added in IHUB-WP-0009-T05)
• Controller: Web/Controller/HubCapabilityManifests.hs
• Guide: docs/domain-hub-extension-guide.md
• Phase 10 dependency: Hub Registry = active manifests + health snapshots