generated from coulomb/repo-seed
281 lines
10 KiB
Markdown
281 lines
10 KiB
Markdown
---
|
|
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: done
|
|
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`.
|
|
|
|
Completed 2026-06-27: implemented the direct activity-core Core Hub path in
|
|
`ACTIVITY-WP-0017` via a `core-hub-interaction-event` ops evidence sink.
|
|
The sink reads runtime credentials from `CORE_HUB_RUNTIME_TOKEN_FILE` or a
|
|
named environment variable, posts sanitized ops-inventory probe metadata to
|
|
Core Hub `/api/v2/interaction-events`, verifies the event is visible, and
|
|
returns only non-secret ids/statuses. Verified with activity-core unit tests
|
|
and a disposable local Core Hub runtime that accepted an
|
|
`ops-endpoint-verified` event from activity-core and listed it back. The
|
|
deployed activity-core smoke still requires approved `CORE_HUB_BASE_URL`,
|
|
runtime token, and widget id/mapping, so `CORE-WP-0004-T04` remains the
|
|
deployed execution gate rather than an implementation blocker.
|
|
|
|
## Task: Define staging deployment profile
|
|
|
|
```task
|
|
id: CORE-WP-0008-T04
|
|
status: done
|
|
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.
|
|
|
|
Completed 2026-06-27: added the service-repo staging deployment profile:
|
|
Dockerfile, `.dockerignore`, `k8s/railiance-staging/` namespace/runtime
|
|
manifests, `docs/deployment/staging-profile.md`, `make
|
|
staging-profile-check`, `make container-build`, and test coverage for the
|
|
profile checker. The profile defines staging runtime config, database and
|
|
secret references, Alembic migration job, health/readiness probes,
|
|
Railiance-style build/apply commands, rollback notes, and the `CORE-WP-0005-T02`
|
|
staging import handoff. Verified with `make staging-profile-check`,
|
|
`make lint`, `make test`, and `make container-build
|
|
IMAGE_REPOSITORY=core-hub IMAGE_TAG=staging-profile-check`. It
|
|
intentionally does not contain plaintext secret values or claim that a real
|
|
staging cluster has already been deployed.
|
|
|
|
## 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.
|