72 lines
5 KiB
Markdown
72 lines
5 KiB
Markdown
# 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` | Surviving framework/runtime — contracts, ports, package, and primary image |
|
|
| `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`
|
|
|
|
**Transition naming:** `core-hub` remains the current production service and
|
|
rollback authority while `hub-core` becomes the surviving framework/runtime.
|
|
|
|
## 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. Hub-core's packaging, contract, port, and conformance
|
|
foundations are complete, and the joint route-group migration design is
|
|
recorded. Execution now waits on a published immutable hub-core revision, a
|
|
durable PostgreSQL backend, and an internal candidate deployment. The healthy
|
|
service remains the production and rollback authority until dual-run consumer
|
|
gates prove a replacement. See `STATE.md` for current operational truth.
|