coulomb/core-hub
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
core-hub/INTENT.md
tegwick c7b1ebb560
Some checks failed
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / pytest-smoke (push) Failing after 2s
Details
docs: reconcile core hub state and intent
2026-08-21 08:49:15 +02:00

4.8 KiB
Raw 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 production framework layer in the three-repo hub stack:

Repo Role
hub-core Shared library — models, router factories, utils (hub_core.utils)
state-hub Dev coordination — file-first workplans, dev MCP
core-hub Production service — /api/v2, hubs, manifests, operator console

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

Naming: core-hub = core framework runtime. hub-core = core primitives library.

Current State

Core Hub is the verified production /api/v2 runtime at hub.coulomb.social, now running on railiance01 through the rapp-core-hub package. The 2026-08-21 relocation preserved the public contract and durable data, reverified ops-hub and activity-core consumers, and retired the active CoulombCore runtimes and obsolete tunnel. Haskell Inter-Hub remains retired (CORE-WP-0007).

This delivers the practical Gen3 production reset, but not the whole product intent. Messaging, progress/work projections, several durable evidence and decision resources, and a single extension runtime remain outside Core Hub or only partially represented. CORE-WP-0010 tracks absorption into hub-core and repository archive; it is blocked on the runtime packaging, minimal-port, and joint-plan decisions in HUB-WP-0004. The healthy service remains the production and rollback authority until dual-run consumer gates prove a replacement. See STATE.md for current operational truth.