prj-state-hub-retirement/architecture/hub-extension-architecture_v0.1.md

---
id: SHR-ARCH-HUB-0001
type: architecture
title: "Hub-Core and Domain-Extension Architecture v0.1"
status: draft-reviewable
version: "0.1"
created: "2026-08-09"
updated: "2026-08-09"
workplan_task: SHR-WP-0001-T04
depends_on:
  - SHR-ARCH-IA-0001
related:
  - architecture/information-model_v0.1.md
  - the-custodian/canon/standards/orthogonal-architecture_v1.0.md
  - the-custodian/docs/hub-ecosystem-architecture.md
  - the-custodian/docs/hub-ecosystem-capability-bridge.md
  - core-hub/docs/specs/core-hub-architecture.md
  - inventory/state-hub-disposition.yaml
  - GOAL.md
---

# Hub-Core and Domain-Extension Architecture v0.1

## Purpose

Turn Orthogonal Architecture (OA) vocabulary and the HelixForge information
model into an **implementable hub-core + domain-extension contract**: what may
be called a hub, what must remain a functional component or authoritative
service, how extensions register and project, and what conformance means.

This document satisfies the hub/domain-extension portion of the `GOAL.md`
success gates at **draft-reviewable** fidelity. Runtime schemas, OpenAPI, and
automated conformance suites land in child workplans (T05); this repo freezes
the architecture names and rules those workplans implement.

Companion: [`hub-extension-contract_v0.1.yaml`](hub-extension-contract_v0.1.yaml).

---

## Target composition (post State Hub retirement)

```text
                         ┌──────────────────────────────────┐
                         │     Domain hubs (extensions)     │
                         │  ops-hub · fin-hub · (others)     │
                         └───────────────┬──────────────────┘
                                         │ extension contract
                                         │ (manifest, ports, events)
                         ┌───────────────▼──────────────────┐
                         │            hub-core              │
                         │  runtime + contracts + SDK +     │
                         │  registry + projections + MCP    │
                         └───┬──────────┬──────────┬────────┘
                             │          │          │
              ┌──────────────▼──┐  ┌────▼────┐  ┌──▼─────────────┐
              │  repo-manager   │  │ activity│  │ identity/auth  │
              │  (component)    │  │  -core  │  │ audit / issues │
              └────────┬────────┘  └────┬────┘  └───┬────────────┘
                       │                │           │
                       ▼                ▼           ▼
                 Git / repos      schedules     specialized DBs
```

**Consolidation direction (from project goal):** today’s split of
`hub-core` (library) + `core-hub` (production `/api/v2` runtime) + parts of
`state-hub` (projections, messaging, catalogs) converges so that **hub-core is
the surviving framework and runtime**. `core-hub` is archived after cutover
evidence; State Hub is retired after capability dispositions complete.

Until cutover, dual-run and compatibility adapters are allowed; **new permanent
authorities must not be added to State Hub**.

---

## Role taxonomy (normative)

### 1. Hub-core (framework + runtime)

**hub-core** owns:

| Area | Responsibility |
| --- | --- |
| Identity & addressing | Domains, hubs, agents, qualified addresses |
| Interaction | Messages, conversations, interaction events |
| Progress projections | Progress events and orientation summaries |
| Extension registry | Manifests, capability bridge, activation |
| Policy integration | Ports to policy engines (not policy authority itself) |
| Telemetry intake | Token/usage samples, correlation |
| Compatibility surface | `/api/v2` (and successors), MCP orientation tools |
| SDK & contracts | Versioned schemas, client helpers, conformance harness entrypoints |

hub-core **does not** own:

- Git file authority or fix-consistency (repo-manager)
- Domain-specific business data (domain hubs / specialized services)
- Secrets (credential custody)
- Authorization *decisions* (auth service)
- Schedule execution (activity-core)

### 2. Domain hub

A **domain hub** is an extension that represents a **market domain** or an
**orthogonal aspect** (e.g. operations, finance) and participates in HelixForge
via the extension contract.

| Must | Must not |
| --- | --- |
| Declare a hub slug + reuse-surface capability id | Own repository file authority for other repos |
| Publish a versioned capability manifest | Bypass control-plane / policy ports |
| Own its domain data and domain APIs | Be invented merely because a service supports the framework |
| Emit cataloged interaction/domain events | Dual-write competing copies of work records |
| Provide health/readiness for composition | Store raw secrets in manifests or events |

Examples: `ops-hub`, `fin-hub`. Counter-examples: Postgres, NATS, ops-bridge,
repo-manager, activity-core — **not** hubs.

### 3. Functional component

A reusable infrastructure or integration service that **supports** hubs but is
not a domain composition surface.

| Component | Role |
| --- | --- |
| **repo-manager** | Repository representation, work-record index, consistency, governed mutations |
| **activity-core** | Schedules, ops runs, event-triggered automation |
| **issue-core** | Non-repo issue projection (if used) |
| **ops-bridge** | Private connectivity only |

Functional components expose **ports** to hub-core; they do not register as
domain hubs unless they genuinely represent a domain/aspect.

### 4. Authoritative service

A specialized system that retains **execution and data authority** behind an
explicit contract: identity, flex-auth, OpenBao, Forgejo, CNPG, fabric engines,
billing ledgers, etc.

hub-core and domain hubs **adapt** to these services; they do not re-implement
them.

### 5. Projection

A rebuildable read model derived from authorities (files, events, service
APIs). Projections may be served by hub-core or a component; losing a projection
DB must not destroy authority.

### 6. Adapter

A boundary module that translates between hub-core contracts and an external
or component API (e.g. Forgejo adapter, State Hub compatibility adapter during
migration, activity-core sink adapter).

Adapters are versioned with the contract they implement and MUST NOT leak
foreign schemas into domain hubs.

---

## Orthogonal Architecture → implementable binding

| OA dimension | HelixForge binding |
| --- | --- |
| **Stack** | k3s, CNPG, NATS, images, tunnels — ops/platform, not “hubs” |
| **Logic L1 Capability** | `capability.<domain>.<name>` reuse-surface + catalog |
| **Logic L2 Service** | Deployed services realizing capabilities |
| **Logic L3 Composition** | hub-core extension registry + domain hub manifests |
| **Logic L4 Solution** | Products / operator experiences consuming hubs |
| **Plane P1 Workload** | Domain hub and component runtimes |
| **Plane P2 Control** | hub-core registry, policy ports, governed repo commands |
| **Plane P3 Management** | Operator console, MCP, CLIs |
| **Quality** | Sensitivity, retention, provenance from IA model |
| **Capability contract** | Manifest + OpenAPI/events/SLOs (this document) |
| **Intelligence** | Agents via control plane; autonomy lanes on work records |

OA remains the descriptive standard; **this contract is the executable subset**
required for hub composition and State Hub replacement.

---

## Extension contract (v0.1)

### Contract identity

| Field | Rule |
| --- | --- |
| `contract_id` | `helixforge.hub-extension` |
| `contract_version` | semver; v0.1 is draft-reviewable |
| `information_model_ref` | `SHR-ARCH-IA-0001` / `information-model_v0.1` |
| Compatibility | Additive changes OK in minor; breaking changes require major + dual-run window |

### Hub registration package

A domain hub is **conformant to register** when it provides:

1. **Hub descriptor**
   - `hub_slug` (stable)
   - `display_name`
   - `domain` (primary market domain or aspect id)
   - `hub_kind`: `domain` | `aspect`
   - `status`: `draft` | `active` | `deprecated` | `retired`
   - optional VSM annotations (`vsm_system`, `vsm_function`) for operator UX

2. **Reuse-surface capability id**
   - Form: `capability.<domain>.<name>`
   - Authored in the hub’s (or owning) `registry/capabilities/`
   - Referenced by catalog rows and manifests (capability bridge rules)

3. **Capability manifest** (versioned body)
   - `manifest_version`
   - `reuse_surface_id`
   - `provides`: list of capability ids / API groups
   - `consumes`: hub-core ports and peer hubs/components
   - `events_emitted` / `events_consumed` (cataloged types only)
   - `widgets` or operator surfaces (optional)
   - `endpoints` (base URLs or service discovery keys — no secrets)
   - `policy_scopes` (names only; decisions via policy port)
   - `schema_version` for body evolution

4. **Health**
   - liveness + readiness that composition probes can call

5. **Auth consumer registration**
   - API consumer metadata + key **hash/prefix only**

### Ports (hub-core provided)

Domain hubs and components integrate through named ports. Ports are **stable
interfaces**; implementations may move during consolidation.

| Port | Direction | Purpose |
| --- | --- | --- |
| `port.registry` | in | Register/activate hubs and manifests |
| `port.addressing` | out | Resolve agents, hubs, domains |
| `port.messaging` | in/out | Send/receive messages; conversation ids |
| `port.events.progress` | in | Append progress events (coordination audit) |
| `port.events.interaction` | in | Append interaction events (ops/framework evidence) |
| `port.projection.query` | out | Read orientation summaries, registries |
| `port.repo` | out | Address repositories via repo-manager (not raw Git) |
| `port.work` | out | Query work-record index (file authority remains in repos) |
| `port.policy` | out | Evaluate/authorize actions (decision elsewhere) |
| `port.telemetry` | in | Submit cost/usage samples with subject refs |
| `port.schedule` | out | Request activity-core execution (not embed cron) |

**Rule:** domain hubs MUST NOT open direct DB connections to repo-manager or
other hubs’ private schemas; only versioned ports/APIs.

### Events

- Event types are **cataloged** (name, schema version, sensitivity class).
- Progress vs interaction semantics follow IA model + existing event mapping.
- Correlation via `correlation_id` when an action spans kinds.
- Payloads MUST NOT contain secrets.

### Projections

| Projection | Built from | Served by |
| --- | --- | --- |
| Hub registry | descriptors + manifests | hub-core |
| Domain summary | work index + messages + progress | hub-core (replaces State Hub summary) |
| Repo health | repo-manager findings | repo-manager → hub-core facade optional |
| Capability matrix | registry + catalog + manifests | hub-core |
| Ops evidence | interaction events + widgets | hub-core |

Projections declare `rebuild_from` authorities and a consistency check.

### Adapters (migration and permanent)

| Adapter | Role | Lifetime |
| --- | --- | --- |
| **State Hub compatibility** | Present familiar REST/MCP while owners cut over | Until retirement gates |
| **core-hub `/api/v2`** | Preserve ops-hub/activity-core consumers during consolidation into hub-core | Until single runtime serves v2 |
| **repo-manager port adapter** | Normalize repo/work facts to hub-core projections | Permanent |
| **activity-core sink** | Ingest interaction/progress for automation | Permanent |
| **Identity/auth ports** | Subject tokens, never raw passwords | Permanent |

---

## Conformance requirements

Conformance is **tiered**. Child workplans implement automated suites; this
section is the requirement set.

### Tier 0 — Descriptive (now)

- [x] Architecture docs (IA + this document) reviewable
- [x] Machine-readable contract outline YAML
- [x] Inventory capabilities mapped to owners/ports

### Tier 1 — Contract artefacts (hub-core child WP)

A release of `helixforge.hub-extension` MUST ship:

1. JSON Schema (or equivalent) for hub descriptor + manifest body  
2. Catalog schema for event types  
3. OpenAPI fragments or protobuf for each port  
4. Fixtures: at least one sample domain hub package (ops-hub shape)  
5. Compatibility matrix vs prior contract version  

### Tier 2 — Runtime conformance (per hub)

A domain hub is **conformant** when tests prove:

| # | Requirement |
| --- | ---: |
| C1 | Descriptor + manifest validate against schema |
| C2 | `reuse_surface_id` resolves in registry |
| C3 | Health endpoints pass composition probe |
| C4 | Manifest activation is idempotent |
| C5 | Emitted events validate against cataloged schemas |
| C6 | No secret material in events/manifests (static + sample payload checks) |
| C7 | Consumed ports only (deny list of raw foreign DB URLs in config samples) |
| C8 | Correlation id accepted/propagated on multi-kind write paths |
| C9 | Readiness fails closed if required consumes are unavailable |
| C10 | Version negotiation: hub declares min/max contract version |

### Tier 3 — Framework conformance (hub-core)

| # | Requirement |
| --- | ---: |
| F1 | Registry CRUD + activate with audit trail |
| F2 | Progress and interaction families remain distinct |
| F3 | Projection rebuild from authority fixtures |
| F4 | `/api/v2` (or successor) consumer smokes for ops-hub + activity-core |
| F5 | MCP orientation tools bound to projections, not foreign private schemas |
| F6 | Policy port fail-closed on deny/unavailable |
| F7 | Telemetry rejects payloads with secret-like keys (heuristic denylist) |
| F8 | Metadata isolation: host SQLAlchemy `Base` not mixed across runtimes during migration (see hub-core docs) |

### Tier 4 — Migration conformance (State Hub retirement)

Aligned with inventory dispositions and T06 gates:

| # | Requirement |
| --- | ---: |
| M1 | Every `move`/`replace` capability has a named port or owner API |
| M2 | Compatibility adapter feature flags per capability |
| M3 | Row-count / provenance checks on data handoff |
| M4 | Zero normal traffic to State Hub in stabilization window |
| M5 | Rollback path documented and exercised once |

---

## Control-plane rules (OA P2 / Intelligence)

1. All agent and automation **mutations** that affect shared state go through
   hub-core ports or repo-manager governed commands — never silent direct SQL
   from agents.
2. Agentic delegation (OA I5) requires policy port approval paths for
   non-green autonomy lanes.
3. Management plane (CLI, MCP, console) is a client of the same ports as domain
   hubs — no privileged side door without audit.

---

## Mapping from today’s three-repo stack

| Today | Target |
| --- | --- |
| `hub-core` library factories | Remain + grow into SDK of surviving runtime |
| `core-hub` `/api/v2` runtime | Absorbed into hub-core runtime; repo archived |
| `state-hub` work/file consistency | repo-manager |
| `state-hub` messages/progress/domains/catalogs | hub-core |
| `state-hub` dashboard | projection UI clients (hub-core / ops surfaces) |
| `state-hub` suggestions / workstream aliases | retire |
| `ops-hub` | domain/aspect hub via extension contract |
| `fin-hub` | domain hub; fabric authority stays specialized |
| `activity-core` | functional component on `port.schedule` + event sinks |

---

## Implementation sequencing (for T05)

Suggested child streams (ids to be created/linked in T05):

1. **hub-core runtime consolidation** — absorb core-hub runtime, ship contract schemas  
2. **repo-manager extraction** — registry, consistency, work index from State Hub  
3. **extension conformance suite** — Tier 1–3 automation  
4. **compatibility adapters** — State Hub strangler per inventory disposition  
5. **domain hub upgrades** — ops-hub/fin-hub manifest alignment  
6. **State Hub retirement gates** — T06 evidence  

Dependencies: (2) and (1) can parallelize behind the IA+extension freeze; (3)
depends on (1); (4) depends on (1)(2); (6) depends on (4)(5).

---

## Anti-patterns

1. Labeling every microservice a “hub.”  
2. Domain hub importing another hub’s SQLAlchemy models.  
3. Manifest bodies carrying API key material.  
4. New features landing only in State Hub during migration.  
5. Collapsing progress and interaction into one event type.  
6. Repo Manager owning cross-domain inboxes.  
7. hub-core owning Git write authority.  
8. Conformance by documentation only after Tier 1 (must be tests).  

---

## Open questions

1. **Single deployable vs package+host** — hub-core as one service image vs
   library + thin host (target: one primary runtime image; library remains
   importable for tests/embed).  
2. **Widget model** — keep core-hub widgets as first-class or generalize to
   “operator surface” descriptors.  
3. **Multi-tenant hub isolation** — quality Q4 strategy per deployment.  
4. **Contract storage** — manifests only in DB vs file-backed in hub repos +
   index (prefer file-backed declaration + registry projection).  
5. **MCP surface split** — one hub-core MCP vs per-component MCP with gateway.

---

## Acceptance for T04

- [x] Domain hub vs functional component vs authoritative service defined  
- [x] hub-core responsibilities and non-goals listed  
- [x] Extension package (descriptor, manifest, ports, events, projections) specified  
- [x] OA dimensions bound to implementable artefacts  
- [x] Conformance tiers 0–4 defined  
- [x] Machine-readable contract outline YAML  
- [x] Migration mapping from current three-repo stack  
- [ ] Automated conformance suite (child WP; not this task)  
- [ ] Human review before treating contract as fleet-normative  

## Related

- `architecture/information-model_v0.1.md` — kinds and authority  
- `inventory/README.md` — capability dispositions  
- `orthogonal-architecture_v1.0.md` — descriptive OA standard  
- `hub-ecosystem-capability-bridge.md` — capability id bridging