the-custodian/docs/core-hub-helixforge-build-alignment.md

# 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=<commit> make container-build`.
3. 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.
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:<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.