feat: add hub runtime and extension contract
This commit is contained in:
parent
fce19f193f
commit
7e1ec03f0c
44 changed files with 3875 additions and 84 deletions
57
INTENT.md
57
INTENT.md
|
|
@ -2,32 +2,35 @@
|
|||
|
||||
**Project:** `hub-core`
|
||||
**Domain:** `infotech`
|
||||
**Status:** Active — library anchor for hub ecosystem (`CUST-WP-0057`)
|
||||
**Updated:** 2026-07-09
|
||||
**Status:** Active — surviving hub framework and runtime (`HUB-WP-0004`)
|
||||
**Updated:** 2026-08-21
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
`hub-core` provides the contracts, reusable primitives, and surviving runtime
|
||||
for HelixForge hubs without absorbing domain authorities or repository-owned
|
||||
work records.
|
||||
|
||||
---
|
||||
|
||||
## Ecosystem position
|
||||
|
||||
`hub-core` is the **library layer** in the three-repo hub stack:
|
||||
`hub-core` is the **surviving framework and runtime** in the consolidating
|
||||
three-repo hub stack:
|
||||
|
||||
| Repo | Role |
|
||||
| --- | --- |
|
||||
| `hub-core` | Shared Python package — this repo |
|
||||
| `state-hub` | Dev coordination host (primary consumer) |
|
||||
| `core-hub` | Production framework (`/api/v2`; adopts hub-core utils) |
|
||||
| `hub-core` | Shared Python package plus target framework/runtime — this repo |
|
||||
| `state-hub` | Legacy coordination host; capabilities move or retire incrementally |
|
||||
| `core-hub` | Current `/api/v2` runtime; routes are absorbed, then the repo is archived |
|
||||
|
||||
Canon: `/home/worsch/the-custodian/docs/hub-ecosystem-architecture.md`
|
||||
|
||||
**Naming:** `hub-core` = core *primitives* (library). `core-hub` = core *framework* (service). Do not conflate them.
|
||||
**Transition naming:** `hub-core` is the surviving product name. `core-hub`
|
||||
names the current service being absorbed; keep the distinction only while the
|
||||
compatibility and cutover work remains.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -52,12 +55,15 @@ package own only its domain-specific tables, workflows, and policies.
|
|||
|
||||
## Governing principle
|
||||
|
||||
> **Hub-core is a library, not a hub.**
|
||||
> **Hub-core is the framework and runtime substrate, not a domain hub or a
|
||||
> repository authority.**
|
||||
|
||||
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.
|
||||
Today it ships models, schemas, router factories, migration scaffolds,
|
||||
utilities, and an optional FastMCP base server. Under
|
||||
`SHR-ARCH-HUB-0001`, those importable surfaces remain while hub-core grows into
|
||||
the surviving runtime. `ADR-0001` selects a primary OCI image built from this
|
||||
repository while keeping the wheel importable; that packaging must not move
|
||||
domain authority into hub-core.
|
||||
|
||||
`hub-core` should answer:
|
||||
|
||||
|
|
@ -77,7 +83,8 @@ remain in `state-hub` and other host implementations.
|
|||
|
||||
## What it is
|
||||
|
||||
`hub-core` is the **shared Python package** for FOS hub services.
|
||||
`hub-core` is the **shared Python package and target runtime** for HelixForge
|
||||
hub composition.
|
||||
|
||||
Current package surface (`hub_core/`):
|
||||
|
||||
|
|
@ -87,6 +94,7 @@ Current package surface (`hub_core/`):
|
|||
| `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 |
|
||||
| `contracts/` | Packaged `helixforge.hub-extension` schemas, named-port OpenAPI, catalogs, fixtures, compatibility |
|
||||
| `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 |
|
||||
|
|
@ -100,8 +108,8 @@ models where extended, and workflow callbacks.
|
|||
|
||||
| Concern | Owner |
|
||||
|---|---|
|
||||
| Running production hub deployment | `state-hub`, `ops-hub`, future hubs |
|
||||
| Topics, workplans, tasks, decisions, SBOM, token accounting | `state-hub` (dev-hub layer) |
|
||||
| Repository-owned workplans, tasks, decisions, and consistency | `repo-manager` over Git authority |
|
||||
| Domain-specific business data and APIs | Domain hubs and specialized services |
|
||||
| Custodian canon, constitution, domain charters | `the-custodian` |
|
||||
| Event-triggered maintenance task creation | `activity-core` |
|
||||
| General issue/task lifecycle outside Custodian workplans | `issue-core` |
|
||||
|
|
@ -118,9 +126,9 @@ acceptance flows) stay in the host hub.
|
|||
|
||||
| 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 |
|
||||
| `state-hub` | Compatibility source during incremental capability cutover |
|
||||
| `core-hub` | `/api/v2` route/runtime source to absorb before archival |
|
||||
| `ops-hub`, `fin-hub`, future hubs | Domain/aspect extensions using versioned hub-core ports and manifests |
|
||||
|
||||
Extraction boundary and migration status:
|
||||
`/home/worsch/the-custodian/docs/hub-core-extraction-boundary.md`
|
||||
|
|
@ -134,8 +142,9 @@ Extraction boundary and migration status:
|
|||
- 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
|
||||
- the surviving runtime exposes versioned `helixforge.hub-extension` ports and projections
|
||||
- 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)
|
||||
- repository work authority and domain-specific business models never migrate into hub-core
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -145,9 +154,11 @@ Extraction boundary and migration status:
|
|||
- Owning PostgreSQL instance provisioning for any environment
|
||||
- Becoming a general application framework unrelated to hub-shaped services
|
||||
- Absorbing reuse-surface capability maturity registry semantics
|
||||
- Owning Git mutation, work-record reconciliation, authorization decisions, secrets, or scheduling
|
||||
|
||||
---
|
||||
|
||||
## Working mantra
|
||||
|
||||
> Extract once what every hub needs; keep domain drama in the hub that owns it.
|
||||
> Centralize the hub contract; keep every authority with the component or
|
||||
> domain that owns it.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue