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.
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.
