core-hub/README.md

# Core Hub

Core Hub is the 3rd-generation Production Interaction Framework for Coulomb / Helixforge.

## Hub stack glossary

| Name | Role |
| --- | --- |
| **hub-core** | Shared library — `hub_core` utils, models, router factories |
| **state-hub** | Dev coordination — file-first workplans, agent MCP |
| **core-hub** | This repo — production `/api/v2` framework |

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

It carries forward the lessons from State Hub and Inter-Hub: workplans and progress need to be durable, domains need typed ways to publish state and evidence, operators need a coherent console, and agents need APIs that are predictable enough to automate against. The rebuild moves that intent onto a lighter production platform.

## Generations

- Gen 1: `state-hub` - file-backed workplans, tasks, progress, messages, and read-model synchronization.
- Gen 2: `inter-hub` - the integrated hub framework idea: manifests, widgets, registries, events, API consumers, and a shared UI, implemented in Haskell/IHP.
- Gen 3: `core-hub` - the same framework ambition rebuilt contract-first on the natural Coulomb stack.

## Initial Stack Direction

- Python 3.12
- FastAPI and Pydantic v2
- SQLAlchemy async, Alembic, asyncpg, Postgres
- pytest and contract fixtures
- OpenAPI and JSON Schema for public contracts
- whynot-design aligned UI components/adapters where operator UI is needed
- Docker/Kubernetes/ArgoCD on the normal Railiance platform path

## Key Documentation

- [INTENT.md](INTENT.md) - purpose, lineage, principles, and platform direction
- [SCOPE.md](SCOPE.md) - repo boundary
- [Research artifact](docs/research/2026-06-27-core-hub-lineage-and-platform-reset.md) - what we learned from State Hub, Inter-Hub, Haskell/IHP, and whynot-design
- [Specs index](docs/specs/README.md) - contract and implementation specification map
- [Workplans](workplans/) - staged implementation plan using ADR-001 workplan files

## Immediate Work

1. Freeze the Core Hub contract and IR.
2. Build the FastAPI/Postgres foundation.
3. Preserve critical Inter-Hub `/api/v2` compatibility for current consumers.
4. Migrate data and cut over production traffic.
5. Retire the Haskell/IHP build lane only after replacement evidence exists.
Update README.md 2026-06-27 08:25:08 +00:00			`# Core Hub`

Set up Core Hub framework planning 2026-06-27 11:00:12 +02:00			`Core Hub is the 3rd-generation Production Interaction Framework for Coulomb / Helixforge.`
Update README.md 2026-06-27 08:25:08 +00:00
feat(ecosystem): adopt hub-core dependency and CI pin gate (CORE-WP-0009) 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. 2026-07-11 01:26:53 +02:00			`## Hub stack glossary`

			`\| Name \| Role \|`
			`\| --- \| --- \|`
			\| hub-core \| Shared library — `hub_core` utils, models, router factories \|
			`\| state-hub \| Dev coordination — file-first workplans, agent MCP \|`
			\| core-hub \| This repo — production `/api/v2` framework \|

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

Set up Core Hub framework planning 2026-06-27 11:00:12 +02:00			`It carries forward the lessons from State Hub and Inter-Hub: workplans and progress need to be durable, domains need typed ways to publish state and evidence, operators need a coherent console, and agents need APIs that are predictable enough to automate against. The rebuild moves that intent onto a lighter production platform.`
Update README.md 2026-06-27 08:25:08 +00:00
Set up Core Hub framework planning 2026-06-27 11:00:12 +02:00			`## Generations`
Initial commit 2026-06-27 08:22:42 +00:00
Set up Core Hub framework planning 2026-06-27 11:00:12 +02:00			- Gen 1: `state-hub` - file-backed workplans, tasks, progress, messages, and read-model synchronization.
			- Gen 2: `inter-hub` - the integrated hub framework idea: manifests, widgets, registries, events, API consumers, and a shared UI, implemented in Haskell/IHP.
			- Gen 3: `core-hub` - the same framework ambition rebuilt contract-first on the natural Coulomb stack.
Initial commit 2026-06-27 08:22:42 +00:00
Set up Core Hub framework planning 2026-06-27 11:00:12 +02:00			`## Initial Stack Direction`
Initial commit 2026-06-27 08:22:42 +00:00
Set up Core Hub framework planning 2026-06-27 11:00:12 +02:00			`- Python 3.12`
			`- FastAPI and Pydantic v2`
			`- SQLAlchemy async, Alembic, asyncpg, Postgres`
			`- pytest and contract fixtures`
			`- OpenAPI and JSON Schema for public contracts`
			`- whynot-design aligned UI components/adapters where operator UI is needed`
			`- Docker/Kubernetes/ArgoCD on the normal Railiance platform path`
Initial commit 2026-06-27 08:22:42 +00:00
Set up Core Hub framework planning 2026-06-27 11:00:12 +02:00			`## Key Documentation`
Initial commit 2026-06-27 08:22:42 +00:00
Set up Core Hub framework planning 2026-06-27 11:00:12 +02:00			`- [INTENT.md](INTENT.md) - purpose, lineage, principles, and platform direction`
			`- [SCOPE.md](SCOPE.md) - repo boundary`
			`- [Research artifact](docs/research/2026-06-27-core-hub-lineage-and-platform-reset.md) - what we learned from State Hub, Inter-Hub, Haskell/IHP, and whynot-design`
			`- [Specs index](docs/specs/README.md) - contract and implementation specification map`
			`- [Workplans](workplans/) - staged implementation plan using ADR-001 workplan files`

			`## Immediate Work`

			`1. Freeze the Core Hub contract and IR.`
			`2. Build the FastAPI/Postgres foundation.`
			3. Preserve critical Inter-Hub `/api/v2` compatibility for current consumers.
			`4. Migrate data and cut over production traffic.`
			`5. Retire the Haskell/IHP build lane only after replacement evidence exists.`