inter-hub/workplans/IHUB-WP-0019-vsm-hub-bootstrap-api.md

id, type, title, domain, repo, status, owner, topic_slug, created, updated, planning_priority, planning_order, related_repos, related_workplans, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	planning_priority	planning_order	related_repos	related_workplans	state_hub_workstream_id
IHUB-WP-0019	workplan	VSM Hub Bootstrap API Hardening	inter_hub	inter-hub	active	codex	inter_hub	2026-05-16	2026-05-16	high	19	helix-forge	HF-WP-0001	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:

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

id: IHUB-WP-0019-T01
status: todo
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.

---

T02 — Add manifest and policy-scope API support

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

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

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

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

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

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.