core-hub/workplans/CORE-WP-0008-api-first-ops-evidence-continuation.md

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
CORE-WP-0008	workplan	API-first ops-hub evidence continuation	infotech	core-hub	finished	codex	custodian	2026-06-27	2026-06-27	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

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

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

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

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

id: CORE-WP-0008-T05
status: done
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.

Completed 2026-06-27: added scripts/core_hub_cli.py backed by core_hub.operator_cli, plus make operator-cli, documentation, and tests. The CLI wraps the existing deployed smoke logic, protected /api/v2 ops-hub bootstrap status checks, migration validate/import code, and a cutover readiness summary over non-secret evidence reports. It reports ids, counts, statuses, and key prefixes only; no full token material is emitted.

Task: Gate and design the web UI rebuild

id: CORE-WP-0008-T06
status: done
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.

Completed 2026-06-27: added docs/specs/operator-ui-rebuild-backlog.md as the compact rebuild backlog extracted from CORE-WP-0006. The backlog gates UI implementation behind deployed API smoke and CLI parity, maps the first screens to Core Hub API resources and CLI equivalents, records whynot component/token consumption, preserves desktop/mobile/no-overlap/non-secret visual checks, and explicitly avoids expansion beyond readiness, registry, evidence, migration/cutover, action-required gates, and access metadata.

Task: Report replacement evidence back to Custodian

id: CORE-WP-0008-T07
status: done
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.

Completed 2026-06-27: reported the replacement evidence back to Custodian in the-custodian commit 12600c5 by adding docs/core-hub-replacement-evidence.md and updating CUST-WP-0052, CUST-WP-0047, and CUST-WP-0049. The handoff records that Core Hub now has the repeatable API smoke harness, activity-core sink, staging profile, CLI wrappers, and gated UI backlog, but no live deployed Core Hub smoke ids/counts were available because no approved deployed endpoint/token was present. CUST-WP-0047-T05 and CUST-WP-0049-T06 therefore remain legacy/fallback wait tasks. The handoff gives rewrite guidance for CUST-WP-0025-T13 through T19 and keeps CORE-WP-0007 blocked until staging import, dual-run/cutover, rollback evidence, and operator approval exist.

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.