72 lines
4.9 KiB
Markdown
72 lines
4.9 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 **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.
|