--- id: CORE-WP-0008 type: workplan title: "API-first ops-hub evidence continuation" domain: infotech repo: core-hub status: active owner: codex topic_slug: custodian created: "2026-06-27" updated: "2026-06-27" state_hub_workstream_id: "cc49cc00-2eb3-43e0-bed8-93cdf919d620" --- # API-first ops-hub evidence continuation ## Goal Turn the local Core Hub replacement evidence into a deployed, operator-safe ops-hub evidence lane that can supersede the old Haskell Inter-Hub bootstrap path. This workplan sequences the implementation in the order requested by Custodian: 1. API first: deployed `/api/v2` compatibility, bootstrap, evidence, and migration/cutover smokes. 2. CLI second: thin wrappers around proven APIs for attended operations and automation. 3. Web UI third: rebuild the operator surface after the API/CLI contract is stable, using whynot-design where practical. This is the Core Hub execution counterpart to `CUST-WP-0052`. ## Current Starting Point Core Hub already has strong local evidence: - `CORE-WP-0004-T01/T02` implemented public/protected `/api/v2` compatibility. - The real `ops-hub/scripts/ops-hub-bootstrap-api.py` passed locally against Core Hub with a throwaway operator token and SQLite smoke DB. - `CORE-WP-0005-T01` implemented the `core-hub.migration.v1` bundle validator and importer plus persisted `migration_runs` evidence. - `CORE-WP-0006` finished the protected `/console` prototype and desktop/mobile visual checks. The remaining gap is production-like evidence: deployed runtime, approved credential routing, activity-core consumer proof, staging import, dual-run smokes, and cutover readiness. ## Constraints - Do not request or print secret values. Use approved custody routes and record non-secret evidence only. - Preserve Haskell Inter-Hub as legacy compatibility / rollback until Core Hub replacement evidence is sufficient. - Keep API/CLI parity: anything operationally important in the UI must also be possible through API and preferably a CLI/script wrapper. - The UI rebuild must not start by recreating every old screen. Prioritize readiness, hub registry, evidence intake, migration/cutover state, and action-required gates. - whynot-design is the preferred source for shared visual language and component semantics; Core Hub must not fork its tokens/contracts silently. ## Task: Capture API-first continuation plan ```task id: CORE-WP-0008-T01 status: done priority: high state_hub_task_id: "6bcfaf19-49d3-4193-8337-5e2c28705cc1" ``` Create this workplan, link it to the existing compatibility, migration, and UI workplans, and make the API-first/CLI-second/UI-third sequence explicit. Done when a future agent can pick the next implementation task without deciding whether to continue old Inter-Hub bootstrap work or Core Hub replacement work. Completed 2026-06-27: created this workplan as the Core Hub counterpart to `CUST-WP-0052`. ## Task: Build deployed API smoke harness ```task id: CORE-WP-0008-T02 status: done priority: high state_hub_task_id: "6a594f9e-01ab-4be5-bf9f-2571722818c5" ``` Add a reusable smoke harness for a deployed Core Hub endpoint. Minimum behavior: - accept `CORE_HUB_BASE_URL` and approved operator/runtime key input through a file or environment path that does not print the value; - probe `/healthz`, `/readyz`, `/api/v2/openapi.json`, public catalogs, and protected-route `401` behavior; - run the ops-hub bootstrap path against Core Hub and verify hub, manifest, API consumer, API key prefix, widgets, hub registry, and one interaction event; - emit a non-secret JSON evidence report with ids, counts, statuses, key prefixes only, and failure reasons; - add a Make target so the smoke can be run consistently in staging and later production. This closes the practical gap behind `CORE-WP-0004-T03` when run against a real deployed Core Hub runtime with approved custody. Completed 2026-06-27: added the reusable deployed API smoke harness (`scripts/core_hub_deployed_smoke.py`, `core_hub.smoke`) plus `make deployed-smoke`, documentation, and unit coverage. The harness probes health/readiness, public catalogs, OpenAPI compatibility, unauthenticated protected-route `401` behavior, operator auth, and a repeatable ops-hub bootstrap-equivalent sequence that creates a smoke hub, manifest, API consumer, API key prefix evidence, widget, interaction event, and hub registry proof. It emits non-secret JSON evidence only. Verified with `make lint`, `make test`, and `make deployed-smoke` against a disposable local HTTP Core Hub runtime. The harness was not executed against a real deployed endpoint in this session because no approved deployed `CORE_HUB_BASE_URL` and operator token were available; `CORE-WP-0004-T03` therefore remains the deployed execution gate. ## Task: Prove activity-core consumer path ```task id: CORE-WP-0008-T03 status: todo priority: high state_hub_task_id: "a24bcbd8-35a3-471b-bd7c-3a75e014c233" ``` Define and prove how activity-core sends ops evidence during the transition. Acceptable outcomes: - direct Core Hub sink using `/api/v2/interaction-events`; or - explicit dual-run bridge where activity-core writes State Hub and Core Hub; or - documented State Hub fallback decision with a date/condition for retrying Core Hub. Done when an activity-core smoke emits a known-safe event that is visible in Core Hub or the fallback decision is recorded with non-secret evidence. This closes or supersedes `CORE-WP-0004-T04`. ## Task: Define staging deployment profile ```task id: CORE-WP-0008-T04 status: todo priority: high state_hub_task_id: "fc53da17-485d-438c-986f-38d688d75b51" ``` Prepare the deployment profile needed before production cutover work. Minimum scope: - runtime config and database settings for a staging Core Hub API; - Alembic migration/runbook path; - approved secret references without plaintext values; - health/readiness and rollback notes; - Helixforge/Railiance build and release commands to use consistently; - documented relationship to `CORE-WP-0005-T02` staging import. Done when Core Hub can be deployed to staging and used by T02/T03 smokes without one-off shell reconstruction. ## Task: Add CLI wrappers after API proof ```task id: CORE-WP-0008-T05 status: todo priority: medium state_hub_task_id: "a8b5d576-428e-4060-bf3d-46f54541bbe1" ``` Build thin CLI/script wrappers around proven API operations. Initial commands should cover: - deployed smoke evidence; - ops-hub bootstrap/status check; - migration bundle validate/import status; - dual-run/cutover readiness summary. The CLI must call the same API paths as tests and smokes. It must not become a second implementation of Core Hub behavior. ## Task: Gate and design the web UI rebuild ```task id: CORE-WP-0008-T06 status: todo priority: medium state_hub_task_id: "5ef0cf2b-3a01-464b-a377-22f5fedff9ad" ``` Turn the finished `/console` prototype into a rebuild backlog only after the API and CLI surfaces above are stable. Minimum scope: - identify the first operator-critical screens and controls; - map each screen to Core Hub API resources and CLI equivalents; - define whynot-design token/component consumption for shared primitives; - preserve desktop/mobile visual checks, no-overlap checks, and non-secret UI assertions; - avoid expanding beyond readiness, registry, evidence, migration/cutover, and action-required gates until those views are excellent. Done when `CORE-WP-0006` prototype lessons become a compact implementation backlog rather than a broad UI rewrite. ## Task: Report replacement evidence back to Custodian ```task id: CORE-WP-0008-T07 status: todo priority: medium state_hub_task_id: "c8d4bb9b-d204-46ae-b727-eafe7b80236f" ``` Feed the replacement evidence back to Custodian so `CUST-WP-0052` can rewind `CUST-WP-0025` safely. Minimum scope: - post State Hub progress with deployed API smoke ids/counts; - record whether `CUST-WP-0047-T05` and `CUST-WP-0049-T06` should close by Core Hub evidence or remain as legacy fallback tasks; - provide enough evidence for Custodian to rewrite or cancel `CUST-WP-0025-T13` through `T19`; - keep Haskell retirement (`CORE-WP-0007`) blocked until cutover proof exists. ## Acceptance - Core Hub has a repeatable deployed API smoke harness for ops-hub bootstrap and evidence intake. - activity-core has a proven Core Hub path or an explicit fallback decision. - staging deployment/import/cutover work can run from documented commands and non-secret evidence, not from memory. - CLI wrappers exist only around stable API behavior. - UI rebuild work is gated behind API and CLI readiness and uses whynot-design where practical. - Custodian receives enough evidence to reset `CUST-WP-0025` and supersede the old Inter-Hub-first path. ## Related Workplans - `CORE-WP-0004` - compatibility and consumer smokes. - `CORE-WP-0005` - data migration and cutover. - `CORE-WP-0006` - console prototype and visual checks. - `CORE-WP-0007` - Haskell retirement, still gated. - `CUST-WP-0052` - Custodian-side Core Hub reframe and FOS reset.