---
id: IHUB-WP-0019
type: workplan
title: "VSM Hub Bootstrap API Hardening"
domain: inter_hub
repo: inter-hub
status: active
owner: codex
topic_slug: inter_hub
created: "2026-05-16"
updated: "2026-05-16"
planning_priority: high
planning_order: 19
related_repos:
  - helix-forge
related_workplans:
  - HF-WP-0001
state_hub_workstream_id: "ebde2b8b-8863-4008-9ebf-9bb0300d7375"
---

# VSM Hub Bootstrap API Hardening

## Goal

Make Inter-Hub capable of bootstrapping VSM domain hubs, starting with
`ops-hub`, through documented API calls or an explicit admin bootstrap command
instead of manual UI-only setup or ad hoc database migrations.

This workplan is linked from `helix-forge` workplan `HF-WP-0001`, where
`ops-hub` is being established as the first VSM Inter-Hub extension.

## Background

The current Inter-Hub implementation already supports the essential concepts:

- `Hub`
- `HubCapabilityManifest`
- type registries for widget types, event types, annotation categories, and
  policy scopes
- `ApiConsumer`
- `ApiKey`
- widgets
- v2 interaction events

However, the live public v2 API is currently read-heavy. The initial
`ops-hub` bootstrap still requires authenticated UI flows or deployment-side
migrations for hub creation, manifest creation/activation, API consumer/key
creation, and widget seeding.

For HelixForge's VSM hub family, the desired repeatable bootstrap shape is:

```text
Hub identity + VSM function + manifest vocabulary + API consumer + seed widgets + evidence events
```

The same shape should later work for:

- `ops-hub` — Operations / System 1
- `syn-hub` — Synchronization / System 2
- `ctl-hub` — Internal Control / System 3
- `aud-hub` — Audit / System 3*
- `int-hub` — Intelligence and Adaptation / System 4
- `pol-hub` — Policy and Identity / System 5
- `env-hub` — Environment boundary

## Constraints

- Preserve the GAAF rule that hub-owned type names are declared through
  `HubCapabilityManifest` before use.
- Do not weaken append-only invariants on `interaction_events`.
- Do not expose raw static API keys after creation.
- Keep UI flows working while adding API/admin bootstrap support.
- Prefer explicit request schemas in OpenAPI instead of reusing response
  schemas as create contracts.

## Tasks

### T01 — Add scriptable hub and widget creation endpoints

```task
id: IHUB-WP-0019-T01
status: done
priority: high
state_hub_task_id: "72c5b7b2-632f-42ab-ac4d-eff123d8f143"
```

Add documented v2 create endpoints for the records needed during a hub
bootstrap:

- `POST /api/v2/hubs`
- `POST /api/v2/widgets`

The endpoints should validate the same invariants as the UI controllers:

- hub slug/name/domain are required
- `hubKind` accepts supported values only
- widget type is registered
- policy scope is registered when the registry is enforced
- widget belongs to an existing hub

Done when: a script can create a hub row and seed widgets without direct DB
access.

Implementation note (2026-05-16): added authenticated v2 `POST /api/v2/hubs`
and `POST /api/v2/widgets`, with required-field validation, hub-kind/status
validation, widget type and policy-scope registry checks, hub existence checks,
initial widget-version snapshots, OpenAPI path entries, SDK helper methods, and
focused Hspec helper coverage. The collection controllers now dispatch
GET/POST by HTTP method so the create routes are reachable. Local
`git diff --check` passed; `scripts/compile-check` could not run because this
shell does not have `IHP_LIB`/the IHP dev environment loaded.

---

### T02 — Add manifest and policy-scope API support

```task
id: IHUB-WP-0019-T02
status: todo
priority: high
state_hub_task_id: "46a027d0-4831-40af-b8ae-e1f858cdaef7"
```

Add documented API or admin-command support for:

- `HubCapabilityManifest` draft creation
- manifest vocabulary update
- manifest activation
- listing policy scopes at `/api/v2/policy-scopes`

Done when: manifest activation can be executed without clicking through the UI
and all four type registries are visible through v2 list endpoints.

---

### T03 — Add first-class VSM hub metadata

```task
id: IHUB-WP-0019-T03
status: todo
priority: medium
state_hub_task_id: "a90a0220-3d02-4b97-9fbf-a6bbbfa5019c"
```

Decide where VSM hub-family metadata belongs and implement it consistently.

Candidate fields:

- `hub_family`
- `vsm_function`
- `vsm_system`

Candidate placement:

- new columns on `hubs`
- manifest metadata JSON
- a separate hub classification table

Done when: `ops-hub` can be represented as the VSM Operations / System 1 hub
without hiding that classification inside prose.

---

### T04 — Add API consumer and API key bootstrap support

```task
id: IHUB-WP-0019-T04
status: todo
priority: high
state_hub_task_id: "a50114d7-8719-45d5-9081-948df147d500"
```

Add either documented v2 endpoints or an admin-only bootstrap command for:

- creating an `ApiConsumer`
- binding it to an active manifest
- creating a static API key
- returning the full key exactly once

Done when: an operator can create an ops-hub API credential from a repeatable
command while preserving the one-time secret display invariant.

---

### T05 — Fix interaction-event create contract gaps

```task
id: IHUB-WP-0019-T05
status: done
priority: high
state_hub_task_id: "1febfdb6-757b-420a-b4bd-709ce3cd1252"
```

Fix the current v2 interaction event create behavior:

- decode active manifest `declaredEventTypes` instead of treating it as empty
- persist submitted `metadata` if metadata is part of the create contract
- dispatch webhooks using the submitted event type instead of hard-coded
  `"clicked"`
- add tests around manifest-declared domain events

Done when: `ops-endpoint-verified` can be submitted with metadata and routed
as an ops-owned event.

Implementation note (2026-05-16): v2 interaction-event creation now validates
against active manifest-declared event types, persists submitted metadata from
JSON request bodies, dispatches webhooks with the submitted event type, and has
focused Hspec coverage for manifest-declared ops domain events. Local
`git diff --check` passed; `scripts/compile-check` could not run because this
shell does not have `IHP_LIB`/the IHP dev environment loaded.

---

### T06 — Update OpenAPI request schemas and hub quickstart docs

```task
id: IHUB-WP-0019-T06
status: todo
priority: medium
state_hub_task_id: "84c92e05-3e0f-490a-a48f-e2d9ddace764"
```

Update OpenAPI and docs to match the real API:

- add distinct create request schemas for hubs, widgets, annotations,
  interaction events, manifests, consumers, and keys where applicable
- remove or clearly mark aspirational quickstart calls until the endpoints
  exist
- document the VSM hub bootstrap recipe using `ops-hub` as the example

Done when: a new hub implementer can follow docs without discovering missing
API endpoints at runtime.

---

### T07 — Add an ops-hub bootstrap smoke test

```task
id: IHUB-WP-0019-T07
status: todo
priority: medium
state_hub_task_id: "409b5f85-ec97-42e4-ad21-09e91b49639c"
```

Add a smoke test or scripted check that exercises the full bootstrap path:

1. create `ops-hub`
2. create and activate the manifest
3. create API consumer/key
4. seed a widget
5. submit an `ops-endpoint-verified` event with metadata
6. verify the event is listed by v2

Done when: the next VSM hub can be bootstrapped by adapting the same script
and changing only vocabulary/configuration values.

## Acceptance Criteria

This workplan is complete when:

1. `ops-hub` can be created without direct DB access.
2. Its manifest can be created and activated without manual UI-only steps.
3. Its API consumer/key can be created by a repeatable operator path.
4. Its widgets can be seeded by API or a documented admin command.
5. Its first operational event can persist metadata and dispatch webhooks using
   the actual submitted event type.
6. OpenAPI and docs accurately describe the supported bootstrap path.
7. The same path is reusable for `syn-hub`, `ctl-hub`, `aud-hub`, `int-hub`,
   `pol-hub`, and `env-hub`.