coulomb/core-hub
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
core-hub/INTENT.md
tegwick f97b793af8
Some checks failed
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / pytest-smoke (push) Failing after 1s
Details
docs: record hub-core production cutover
2026-08-21 21:07:09 +02:00

4.9 KiB
Raw Permalink Blame History

INTENT - Core Hub

Purpose

Core Hub is the 3rd-generation Production Interaction Framework for Coulomb / Helixforge.

It rebuilds the goals of the 2nd-generation Inter-Hub idea on a practical production stack: contract-first, Python/FastAPI/Postgres at the service layer, explicit compatibility tests, and UI patterns that can flow from the whynot-design process without binding the system to one framework or one agent runtime.

Lineage

  • Generation 1: state-hub proved file-backed workplans, State Hub read models, progress events, messages, tasks, and agent coordination.
  • Generation 2: inter-hub introduced the broader hub framework idea: separate domain hubs, shared manifests, widgets, registries, events, and a unified operator surface. The idea was right, but the Haskell/IHP/Nix path was too heavy for the available infrastructure.
  • Generation 3: core-hub keeps the Inter-Hub ambition but makes it operationally ordinary: simple local development, fast tests, visible contracts, migration discipline, and deployment through the existing Railiance platform rather than a bespoke Haskell build lane.

Product Intent

Core Hub should become the production interaction substrate where domains publish state, capabilities, evidence, decisions, workplans, agent messages, registry facts, and operator UI components through one coherent framework.

The framework must be usable by humans and agents. Human operators need a stable console and clear audit trail. Agents need typed APIs, predictable workflows, and durable contract documentation. Downstream hubs need a way to integrate without inheriting Core Hub internals.

Core Principles

  1. Contract first: schemas, OpenAPI, event catalogs, capability manifests, and compatibility tests precede implementation convenience.
  2. Adapter friendly: the core model is independent from any one UI or service framework. Implementations consume the contract, they do not become the contract.
  3. Operationally light: local setup, tests, and deployment must fit the natural Coulomb stack and avoid special-purpose Haskell/Nix build paths.
  4. Migration honest: Core Hub preserves the useful Inter-Hub semantics while making incompatibilities explicit and testable.
  5. Credential-safe: no secrets in Git, State Hub, workplans, logs, or chat. Credential ownership follows the ops-warden/OpenBao/key-cape routing model.
  6. Agent-native: workplans remain file-first, State Hub remains a read/cache/index layer until Core Hub intentionally replaces or absorbs that role.
  7. Self-optimizing: regular reviews identify recurring error states, necessary workarounds, needless complexity from unnecessary information passing, and other inefficiencies so the framework can simplify its own operating patterns over time.

Initial Platform Direction

  • Backend: Python 3.12, FastAPI, Pydantic v2, SQLAlchemy async, Alembic, asyncpg/Postgres, httpx.
  • Contracts: OpenAPI, JSON Schema, SQL/Alembic migrations, registry YAML/Markdown where appropriate.
  • Tests: pytest, contract fixtures, API compatibility tests, migration checks.
  • UI: whynot-design aligned tokens and Lit/custom-element adapters where UI components are needed; avoid locking the framework to React.
  • Deployment: Docker/Kubernetes/ArgoCD/Gitea or Forgejo workflows on the normal platform path; no GHC/IHP/Nix build dependency for the new framework.

Ecosystem position

core-hub is the previous production service and temporary rollback in the three-repo hub stack:

Repo Role
hub-core Surviving framework/runtime — contracts, ports, package, and primary image
state-hub Dev coordination — file-first workplans, dev MCP
core-hub Previous production service retained through cutover stabilization

Canon: /home/worsch/the-custodian/docs/hub-ecosystem-architecture.md

Transition naming: hub-core is the production service and surviving framework/runtime. core-hub is the tested rollback until archive.

Current State

Hub-core is the verified production /api/v2 runtime at hub.coulomb.social, running on railiance01 through the rapp-core-hub package. The 2026-08-21 cutover preserved the public contract and exact durable data, reverified ops-hub and activity-core consumers, enforced one writer per group, and exercised rollback to Core Hub plus forward recovery. Core Hub is still deployed with no writer groups through the seven-day stabilization window; the active CoulombCore runtimes and obsolete tunnel remain retired. Haskell Inter-Hub remains retired (CORE-WP-0007).

This delivers the practical Gen3 production reset, but not the whole product intent. Fleet development coordination remains in state-hub; progress/work projections and several durable evidence, decision, deployment, and outcome resources are still external or only partially represented. CORE-WP-0010 now tracks only stabilization, residual-owner handoff, and read-only archive. Hub-core revision 055cf49 is the production implementation. See STATE.md for current operational truth.