diff --git a/workplans/IHUB-WP-0019-vsm-hub-bootstrap-api.md b/workplans/IHUB-WP-0019-vsm-hub-bootstrap-api.md new file mode 100644 index 0000000..ba50225 --- /dev/null +++ b/workplans/IHUB-WP-0019-vsm-hub-bootstrap-api.md @@ -0,0 +1,253 @@ +--- +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: 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 + +```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: todo +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. + +--- + +### 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`.