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:

Local contract gate: make lint, make test, make openapi, make staging-profile-check, and git diff --check.
Image build: IMAGE_REPOSITORY=gitea.coulomb.social/coulomb/core-hub IMAGE_TAG=<commit> make container-build.
Registry publication: publish immutable <commit> 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.
Staging deploy: keep k8s/railiance-staging/ as the service-repo profile until railiance-apps owns explicit Core Hub dry-run/status/deploy targets.
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.
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:<commit>.
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.

6.3 KiB Raw Blame History