# 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.