coulomb/prj-state-hub-retirement
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
prj-state-hub-retirement/architecture/hub-extension-architecture_v0.1.md
tegwick 3e3e4c9f0b docs(SHR-WP-0001): complete T04 hub-extension architecture 
Add draft-reviewable hub-core and domain-extension contract
(helixforge.hub-extension v0.1): role taxonomy, ports, manifests,
conformance tiers, and migration stack map.
2026-08-09 18:00:30 +02:00

18 KiB
Raw Permalink Blame History

id type title status version created updated workplan_task depends_on related
SHR-ARCH-HUB-0001 architecture Hub-Core and Domain-Extension Architecture v0.1 draft-reviewable 0.1 2026-08-09 2026-08-09 SHR-WP-0001-T04
SHR-ARCH-IA-0001
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.

Target composition (post State Hub retirement)

                         ┌──────────────────────────────────┐
                         │     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)

  • Architecture docs (IA + this document) reviewable
  • Machine-readable contract outline YAML
  • 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

  • Domain hub vs functional component vs authoritative service defined
  • hub-core responsibilities and non-goals listed
  • Extension package (descriptor, manifest, ports, events, projections) specified
  • OA dimensions bound to implementable artefacts
  • Conformance tiers 0–4 defined
  • Machine-readable contract outline YAML
  • 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