generated from coulomb/repo-seed
Add hub-core package, docs, and State Hub integration scaffold
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.
This commit is contained in:
137
INTENT.md
Normal file
137
INTENT.md
Normal file
@@ -0,0 +1,137 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user