generated from coulomb/repo-seed
tegwick
986ac4d40b
Extract the first reusable slice (models, schemas, routers, MCP, migrations) from state-hub with INTENT/SCOPE, agent instructions, workplan, and aligned inter_hub capability registry index.
137 lines
5.2 KiB
Markdown
137 lines
5.2 KiB
Markdown
# INTENT — hub-core
|
|
|
|
**Project:** `hub-core`
|
|
**Domain:** `inter_hub`
|
|
**Status:** Active extraction (CUST-WP-0025)
|
|
**Updated:** 2026-06-16
|
|
|
|
---
|
|
|
|
## One-line intent
|
|
|
|
`hub-core` provides reusable FastAPI, SQLAlchemy, and MCP primitives so multiple
|
|
FOS hub services can share a common foundation without importing each other's
|
|
domain-specific coordination models.
|
|
|
|
---
|
|
|
|
## Why it exists
|
|
|
|
Custodian and helix_forge ecosystems need more than one hub-shaped service:
|
|
development coordination (`state-hub`), operations (`ops-hub`), finance, and
|
|
future domain hubs. Those services repeat the same patterns — domain registry,
|
|
managed repositories, agent messaging, progress telemetry, capability catalog
|
|
surfaces, third-party service catalog (TPSC), policy lookup, and MCP
|
|
orientation tools.
|
|
|
|
Without `hub-core`, each hub would duplicate SQLAlchemy models, Pydantic
|
|
contracts, router mounting, pagination helpers, and MCP wrappers. That leads to
|
|
schema drift, incompatible agent tools, and expensive extractions every time a
|
|
second hub appears.
|
|
|
|
`hub-core` exists to extract the **generic hub substrate** once and let each hub
|
|
package own only its domain-specific tables, workflows, and policies.
|
|
|
|
---
|
|
|
|
## Governing principle
|
|
|
|
> **Hub-core is a library, not a hub.**
|
|
|
|
It ships models, schemas, router factories, migration scaffolds, utilities, and
|
|
an optional FastMCP base server. A consuming repository (for example
|
|
`state-hub`) wires database sessions, auth, host-specific callbacks, and
|
|
domain-only routes into those factories.
|
|
|
|
`hub-core` should answer:
|
|
|
|
1. **What primitives do all FOS hubs share?** Domains, repos, messages,
|
|
progress events, capability catalog/request read paths, TPSC catalog/snapshots,
|
|
policy lookup, canonical risk/alert event types.
|
|
2. **How do hubs expose them consistently?** Factory-based FastAPI routers and
|
|
matching MCP tools with dependency injection at the host boundary.
|
|
3. **How do hubs evolve schema together?** Shared Alembic templates and a
|
|
documented core-schema migration adopters can extend.
|
|
|
|
It should **not** answer dev-hub questions such as which workstream is blocked,
|
|
which task needs human review, or how kaizen agents spawn maintenance work. Those
|
|
remain in `state-hub` and other host implementations.
|
|
|
|
---
|
|
|
|
## What it is
|
|
|
|
`hub-core` is the **shared Python package** for FOS hub services.
|
|
|
|
Current package surface (`hub_core/`):
|
|
|
|
| Area | Responsibility |
|
|
|---|---|
|
|
| `models/` | SQLAlchemy base, domains, managed repos, agent messages, capability catalog/requests, progress events, TPSC |
|
|
| `schemas/` | Pydantic contracts matching core models plus DoI report shapes |
|
|
| `routers/` | Factory functions: domains, repos, messages, progress, capabilities, TPSC, policy |
|
|
| `mcp/` | `HubCoreMCPServer` — generic orientation, messaging, capability, repo, DoI, TPSC/GDPR, risk/alert, progress tools |
|
|
| `migrations/` | Alembic scaffold and `0001_core_schema` for adopters |
|
|
| `utils/` | Slugs, pagination, repo path resolution, trailing-slash routing |
|
|
| `events.py` | Canonical FOS §10 risk and alert event types |
|
|
|
|
Hosts mount only the routers they need and inject their own `Session` providers,
|
|
models where extended, and workflow callbacks.
|
|
|
|
---
|
|
|
|
## What it is not
|
|
|
|
| Concern | Owner |
|
|
|---|---|
|
|
| Running production hub deployment | `state-hub`, `ops-hub`, future hubs |
|
|
| Topics, workstreams, tasks, decisions, SBOM, token accounting | `state-hub` (dev-hub layer) |
|
|
| Custodian canon, constitution, domain charters | `the-custodian` |
|
|
| Event-triggered maintenance task creation | `activity-core` |
|
|
| General issue/task lifecycle outside Custodian workplans | `issue-core` |
|
|
| Capability reuse registry and federation compose | `reuse-surface` |
|
|
| Network tunnels and remote operations | `ops-bridge` |
|
|
|
|
`hub-core` may define generic capability **catalog** and **request read**
|
|
primitives, but workflow side effects (task unblocking, dispute resolution,
|
|
acceptance flows) stay in the host hub.
|
|
|
|
---
|
|
|
|
## Primary consumers
|
|
|
|
| Consumer | Relationship |
|
|
|---|---|
|
|
| `state-hub` | First adopter; incremental import of schemas, routers, MCP (CUST-WP-0025 T08+) |
|
|
| `ops-hub` | Planned consumer of shared primitives without dev-hub tables |
|
|
| Future FOS hubs | Fin-hub and domain hubs mount subsets of hub-core factories |
|
|
|
|
Extraction boundary and migration status:
|
|
`/home/worsch/the-custodian/docs/hub-core-extraction-boundary.md`
|
|
|
|
---
|
|
|
|
## Success criteria
|
|
|
|
`hub-core` succeeds when:
|
|
|
|
- a new hub can register domains and repos using hub-core routers without copying SQLAlchemy models
|
|
- State Hub pytest suite passes with hub-core as an editable dependency
|
|
- MCP tools for orientation, messages, progress, and TPSC behave consistently across hosts that opt in
|
|
- schema changes to shared primitives are versioned through hub-core migrations, not ad hoc forks
|
|
- dev-hub-specific foreign keys never appear in hub-core models (extension via host callbacks or JSON context fields)
|
|
|
|
---
|
|
|
|
## Non-goals
|
|
|
|
- Replacing FastAPI, SQLAlchemy, or FastMCP
|
|
- Owning PostgreSQL instance provisioning for any environment
|
|
- Becoming a general application framework unrelated to hub-shaped services
|
|
- Absorbing reuse-surface capability maturity registry semantics
|
|
|
|
---
|
|
|
|
## Working mantra
|
|
|
|
> Extract once what every hub needs; keep domain drama in the hub that owns it. |