# 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.