From cac6302a0a09d8e220b406afbb75b9d3040775fa Mon Sep 17 00:00:00 2001 From: tegwick Date: Sat, 27 Jun 2026 22:29:35 +0200 Subject: [PATCH] Align Core Hub build lane with Helixforge --- docs/core-hub-helixforge-build-alignment.md | 139 +++++++++++++++++++ workplans/CUST-WP-0052-core-hub-fos-reset.md | 10 +- 2 files changed, 148 insertions(+), 1 deletion(-) create mode 100644 docs/core-hub-helixforge-build-alignment.md diff --git a/docs/core-hub-helixforge-build-alignment.md b/docs/core-hub-helixforge-build-alignment.md new file mode 100644 index 0000000..467a121 --- /dev/null +++ b/docs/core-hub-helixforge-build-alignment.md @@ -0,0 +1,139 @@ +# Core Hub Helixforge Build Alignment + +Date: 2026-06-27 + +Related workplans: `CUST-WP-0052`, `CUST-WP-0025`, `CORE-WP-0008`, +`CORE-WP-0005`, `CORE-WP-0007`. + +## Sources Reviewed + +- `/home/worsch/helix-forge/SCOPE.md` +- `/home/worsch/helix-forge/workplans/HF-WP-0001-establish-ops-hub-first-extension.md` +- `/home/worsch/helix-forge/wiki/OpsHubBootstrapRunbook.md` +- `/home/worsch/railiance-forge/Makefile` +- `/home/worsch/railiance-forge/docs/initial-operating-contracts.md` +- `/home/worsch/railiance-forge/docs/ci-runner-actions-gitops-ownership.md` +- `/home/worsch/railiance-forge/docs/gitea-actions-runner-substrate.md` +- `/home/worsch/railiance-forge/docs/observability-operating-evidence.md` +- `/home/worsch/railiance-forge/docs/gitea-container-registry.md` +- `/home/worsch/core-hub/Makefile` +- `/home/worsch/core-hub/docs/deployment/staging-profile.md` +- `/home/worsch/core-hub/docs/deployment/operator-cli.md` +- `/home/worsch/core-hub/docs/specs/testing-release-and-migration.md` + +## Takeaways + +HelixForge is currently a capability-first product/architecture and workplan +home, not a deployable runtime. Its older ops-hub Inter-Hub bootstrap material +is useful as vocabulary and historical evidence, but Core Hub now owns the +replacement implementation lane. + +Railiance Forge is the concrete build and artifact practice source. The useful +patterns for Core Hub are: + +- repo-local Make targets are the operator entry point; +- separate read-only checks from deploy/apply actions; +- print evidence docs and runbooks through Make targets where useful; +- source repos own build scripts and image/package metadata; +- `railiance-forge` owns registry endpoints, runner labels, runner health, and + artifact evidence contracts; +- `railiance-apps` should eventually own S5 deployment checks and app release + values; +- runner labels describe capability and trust level, not hostnames; +- privileged labels such as `registry-publish`, `cluster-dry-run`, and + `s5-release-check` require named credential paths and reviewed purpose; +- artifact tags for release evidence should be immutable commit-SHA tags; +- mutable tags such as `latest` must never be the only production reference; +- evidence should capture source repo, commit SHA, artifact identity, + version/tag/digest, runner identity when relevant, smoke result, and consuming + deployment value change; +- docs may reference SOPS/OpenBao/Kubernetes Secret names, but must not contain + decrypted values, tokens, kubeconfigs, SSH keys, or tokenized URLs. + +## Core Hub Current Fit + +Core Hub already has a compatible service-repo surface: + +- `make lint` +- `make test` +- `make openapi` +- `make migrate-validate` +- `make staging-profile-check` +- `make container-build` +- `make deployed-smoke` +- `make operator-cli` +- `make visual-check` + +The current image repository default, +`gitea.coulomb.social/coulomb/core-hub`, matches the Railiance Forge registry +contract. Core Hub staging docs already prefer commit-SHA image tags and note +that production/shared staging deploys must not depend on `latest`. + +The current Core Hub staging profile is acceptable as a near-term service-repo +profile. It should later be promoted into a Railiance app release path once the +API contract and staging evidence are stable. + +## Environment Posture + +Use three distinct postures so build/release work does not overfit to the local +workstation: + +| Posture | Purpose | Core Hub behavior | +|---|---|---| +| Local/dev | Fast contract work and disposable smoke proof. | `uv`, SQLite/disposable DBs, `CORE_HUB_AUTO_CREATE_TABLES=1` only for local smoke/test bootstraps, no live cluster dependency. | +| Staging | Production-like proof without cutover. | Postgres, Alembic migrations only, Kubernetes `core-hub-staging`, commit-SHA images, OpenBao/operator-owned secret references, deployed API and activity-core smokes. | +| Production/cutover | Replacement of Haskell Inter-Hub. | Requires staging import, dual-run or shadow smokes, rollback notes, non-secret readiness summary, and explicit operator approval. | + +Do not let missing runner automation block API contract work. It should block +only publish/deploy automation that actually needs forge runner labels or +cluster credentials. + +## Recommended Core Hub Build Lane + +Keep the existing Core Hub Make targets and add future targets only when they +remove manual release ambiguity: + +1. Local contract gate: + `make lint`, `make test`, `make openapi`, `make staging-profile-check`, + and `git diff --check`. +2. Image build: + `IMAGE_REPOSITORY=gitea.coulomb.social/coulomb/core-hub IMAGE_TAG= make container-build`. +3. Registry publication: + publish immutable `` tags through an attended operator path first; + move to forge runner automation only after `registry-publish` runner evidence + is available for the repo/workflow purpose. +4. Staging deploy: + keep `k8s/railiance-staging/` as the service-repo profile until + `railiance-apps` owns explicit Core Hub dry-run/status/deploy targets. +5. Evidence gate: + run `make deployed-smoke`, activity-core Core Hub sink smoke, migration + import, and `make operator-cli CLI_ARGS="readiness-summary ..."` with + reports under ignored `.local/` paths. +6. Cutover: + require non-secret evidence reports, rollback notes, and operator approval + before `CORE-WP-0007` Haskell retirement can move. + +## Required Follow-Ups + +No HelixForge repo change is required for the Core Hub reset. HelixForge remains +the capability/modeling context, while Core Hub owns the replacement runtime. + +Core Hub follow-ups: + +- Add a future release evidence note or Make target when a real staging image is + published to `gitea.coulomb.social/coulomb/core-hub:`. +- Keep `CORE-WP-0005` staging import and cutover evidence tied to immutable + image tags and non-secret reports. +- Add runner workflow files only after `railiance-forge` has runner label and + registry-publish evidence suitable for Core Hub. + +Railiance follow-ups: + +- `railiance-apps` should eventually own Core Hub app release values and + dry-run/status/deploy targets once the service leaves the temporary + service-repo staging profile. +- `railiance-forge` should be cited for registry, runner, and artifact evidence; + it should not own Core Hub API behavior or cutover decisions. +- Any need for cluster-dry-run or deploy-capable runner labels should be posted + as a State Hub requirement before adding workflow dependencies. + diff --git a/workplans/CUST-WP-0052-core-hub-fos-reset.md b/workplans/CUST-WP-0052-core-hub-fos-reset.md index d40f4de..624b66d 100644 --- a/workplans/CUST-WP-0052-core-hub-fos-reset.md +++ b/workplans/CUST-WP-0052-core-hub-fos-reset.md @@ -194,7 +194,7 @@ retirement is unblocked. ```task id: CUST-WP-0052-T05 -status: todo +status: done priority: medium state_hub_task_id: "b46e608d-0174-422d-baf4-26b5d027e761" ``` @@ -213,6 +213,14 @@ Minimum scope: Done when the Core Hub continuation has a concrete build/test/release surface rather than one-off shell recipes. +Completed 2026-06-27: added `docs/core-hub-helixforge-build-alignment.md`. +The note separates HelixForge's capability/workplan role from Railiance Forge's +concrete build, registry, runner, and evidence contracts. It maps Core Hub's +existing Make targets, staging profile, immutable image-tag expectation, +operator CLI, smoke evidence, and future `railiance-apps` promotion path into a +repeatable build/test/release lane without blocking API contract work on runner +automation. + ## Task: UI Rebuild Criteria ```task