core-hub/docs/research/2026-06-27-core-hub-lineage-and-platform-reset.md

Core Hub Lineage and Platform Reset Research

Date: 2026-06-27 Author: codex Status: seed research artifact

Question

How should Core Hub rebuild the intent of Inter-Hub while retiring Haskell/IHP dependencies and preserving the working infrastructure lessons from State Hub?

Summary

Core Hub should not be a direct port of the Haskell Inter-Hub codebase. It should be a contract-first rebuild of the production interaction framework idea. The important asset is the framework intent: shared hub manifests, typed events, widgets, registries, API consumers, evidence, and operator surfaces. The costly part was the implementation substrate: Haskell/IHP/Nix/GHC/devenv and the special haskelseed build path.

The recommended posture is to extract the contract, preserve compatibility where current consumers depend on /api/v2, then rebuild on the natural Coulomb platform: Python, FastAPI, Pydantic, SQLAlchemy, Alembic, Postgres, pytest, OpenAPI, Docker/Kubernetes, and whynot-design-aligned UI adapters.

Generation 1: State Hub

State Hub proved several durable ideas:

• Workplans should live in repository files first.
• The hub can act as a read/cache/index layer over files.
• Progress events, tasks, messages, and decisions give agents shared operational memory.
• Simple HTTP/REST plus Postgres is enough to make the coordination loop useful.
• File-first synchronization makes agent work inspectable and recoverable.

Limits observed:

• State Hub is coordination infrastructure, not a full interaction framework.
• It does not naturally model rich domain hub manifests, widgets, registry federation, or UI composition.
• The read-model role should be preserved until a replacement proves compatibility.

Generation 2: Inter-Hub

Inter-Hub introduced the right higher-level idea: separate domain hubs should publish into a shared framework with manifests, widgets, interaction events, annotations, registries, API consumers, and an integrated operator UI.

Useful surfaces to preserve:

• /api/v2/hubs
• /api/v2/hub-capability-manifests
• /api/v2/api-consumers
• /api/v2/widgets
• /api/v2/interaction-events
• /api/v2/annotations
• /api/v2/requirement-candidates
• /api/v2/decision-records
• /api/v2/deployment-records
• /api/v2/outcome-signals
• /api/v2/widget-types
• /api/v2/event-types
• /api/v2/annotation-categories
• /api/v2/policy-scopes
• /api/v2/token
• /api/v2/openapi.json
• /api/v2/openapi.yaml
• /api/v2/docs
• SDK endpoints if existing consumers still use them

Operational blockers observed:

• Haskell/IHP demanded too much local and CI infrastructure.
• Nix/GHC/devenv builds were slow and fragile for this environment.
• The haskelseed path became a production gate instead of an implementation detail.
• Basic API issues, such as Postgres COUNT(*) bigint decoding, became hard to prove live because the build/deploy loop was expensive.
• UI ambition was tied to a monolithic framework rather than a neutral component contract.

Haskell Dependency Boundary

Actual Haskell implementations:

1. inter-hub: production framework and API service. High-impact. Retire only after Core Hub compatibility, migration, and cutover evidence.
2. ihp-railiance-probe: small IHP/GHC/Nix probe. Low-impact. Can be renamed or archived early.

Haskell support infrastructure:

• haskelseed runner labels and Gitea workflow paths
• haskell-build VM and build-agent capability
• IHP/GHC/Nix/devenv setup
• production image build path for Inter-Hub

Protocol consumers that are not Haskell:

• ops-hub: Python tooling that calls Inter-Hub /api/v2 bootstrap endpoints.
• activity-core: Python/FastAPI/Temporal stack with optional Inter-Hub sink and State Hub fallback.
• the-custodian: planning and workplan gates.
• Other repos mostly reference Inter-Hub protocols, docs, or concepts rather than depending on Haskell directly.

whynot-design Lesson

The whynot-design direction suggests the right architecture pattern:

• Maintain a canonical design or interaction contract.
• Derive implementation adapters from that contract.
• Keep generated or derived layers distinct from hand-authored behavior.
• Use parity and drift checks rather than assuming codegen solves design.
• Avoid binding the core model to React, IHP, or any single UI framework.

For Core Hub, the equivalent is:

• Contract/IR: schema, OpenAPI, JSON Schema, event catalogs, capability manifests, fixtures, and compatibility tests.
• Runtime adapters: FastAPI service, Python clients, UI component adapters, import/export tools.
• Drift checks: contract tests against legacy Inter-Hub fixtures and known consumers.

Recommended Core Hub Architecture

Core Hub should be layered:

1. Contract and IR layer: OpenAPI, JSON Schema, SQL/Alembic schema, catalogs, fixtures, and compatibility examples.
2. Service layer: FastAPI, Pydantic v2 DTOs, SQLAlchemy async models, Alembic migrations, asyncpg/Postgres, and httpx clients.
3. Compatibility layer: /api/v2 routes, response-shape tests, and auth/error semantics.
4. UI layer: operator console, whynot-design tokens/components, and Lit/custom-element adapters where useful.
5. Migration layer: Inter-Hub schema import/export, row-count checks, fixture replay, and dual-run smokes.

Key Risks

• Accidentally breaking ops-hub bootstrap endpoints.
• Losing Inter-Hub data history during migration.
• Treating API key hashes/prefixes as recoverable secrets. Runtime keys may need approved regeneration.
• Retiring Haskell repos before production traffic has moved.
• Recreating framework coupling by making the UI or service implementation the contract.

Decision Recommendation

Create Core Hub as the new third-generation repo and proceed in stages:

1. Freeze contract and compatibility scope.
2. Build FastAPI/Postgres baseline.
3. Implement /api/v2 compatibility for current consumers.
4. Migrate data and run side-by-side smokes.
5. Cut over production DNS/service path.
6. Rename/archive Haskell repos and retire the build infrastructure.

The IHP probe can be retired first. Production Inter-Hub should be renamed to inter-hub-haskell only after Core Hub passes compatibility and migration gates.