Align Core Hub build lane with Helixforge
This commit is contained in:
139
docs/core-hub-helixforge-build-alignment.md
Normal file
139
docs/core-hub-helixforge-build-alignment.md
Normal file
@@ -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=<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.
|
||||
|
||||
Reference in New Issue
Block a user