tegwick
0709262ffd
Import slugify_or_default from hub-core, add contract tests, vendor hub-core in Docker/Forgejo CI, document metadata isolation and pagination deferral, and align INTENT/SCOPE with three-repo stack.
55 lines
4.1 KiB
Markdown
55 lines
4.1 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` | 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
|
|
|
|
Production serves Core Hub at `hub.coulomb.social` since 2026-07-03. Haskell Inter-Hub is retired (`CORE-WP-0007`). Ecosystem consolidation with hub-core and state-hub is tracked under `CUST-WP-0057` / `CORE-WP-0009`.
|