Set up Core Hub framework planning

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

@@ -0,0 +1,133 @@
+# 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.