[v5] [architect] pkg/hub mixes spoke-side client code and the SaaS control plane in one package (spoke ↔ hub boundary)

[kubestellar-hive]

Architecture Finding

Type: coupling / missing package boundary
Affected area: src/pkg/hub (v5 branch, HEAD 99fca74), importers src/pkg/dashboard and src/cmd/hive

pkg/hub (66,543 non-test lines) contains two deployment roles in a single Go package:

1. SaaS control-plane server — saas_*.go (~27,231 lines across 20 files), server.go (4,460), saas_provision.go, cluster_app_key.go, hub_generations*.go, oauth.go, journey/enrollment/clusters registry, etc.
2. Spoke-side client helpers — heartbeat push (StartHeartbeat, LastHeartbeatAttempt/Success, HeartbeatEnabled as package-level atomics), SSO verification (SpokeSSOPublicKeys, VerifySSOTokenAcrossKeys), terminal assertions (MintTerminalAssertion, TerminalSigningKey), SpokeInviteKey, self-upgrade (UpgradeSelfToSHA, RolloutRestartSelf), fd gauge, cluster-health collection.

The spoke consumers (pkg/dashboard/{api,api_contribute,server,session}.go, cmd/hive/{hubwire,configwire,hookwire,main*}.go) use ~60 spoke-side symbols, yet importing them compiles the entire control plane into every spoke build and couples both roles' internal state.

Much of the shared state is package-level mutable globals (heartbeat atomics, contribute queue/fleet snapshot, signing keys), so the boundary between "what the spoke may call" and "what only the hub process may touch" exists only by convention — nothing structural stops spoke code from reaching into control-plane state (e.g. pkg/dashboard tests already drive hub.ReadyQueue, hub.FleetSnapshot, hub.SetHeartbeatStateForTest).

Impact

• Any hub-internal change recompiles and re-risks every spoke binary; test blast radius is the whole 66k-line package.
• The spoke/hub API contract is invisible — it is whatever symbols happen to be exported, so accidental new couplings (like the ~40-line dashboardHTML JS additions flagged in PR 🌱 feat(hub): watch the wildcard certificate that now serves every spoke (#5977) #6010 review) keep accreting.
• The v5 decomposition ([v5] pkg/hub/saas.go is a 22,488-line single file (190 functions, 23 types) — split the SaaS surface #5564 line) split files but not the package: one import still links both roles.
• Global mutable state makes hub tests non-hermetic and forces *ForTest escape hatches across package lines.

Recommendation

Phase the split along the deployment-role seam, keeping cmd/hive's dual-mode binary intact:

1. Extract spoke-facing client code into pkg/hub/spoke (or pkg/spokeclient): heartbeat push + status, task-status push, SSO verify, terminal assertion mint/verify, invite key, self-upgrade. This is mostly mechanical (move + import rewrite) since these files barely reference saas internals.
2. Move wire/DTO types shared by both sides (HeartbeatPayload, TaskStatusPayload, AgentSummary, LeaderboardEntry, *Wire types) into pkg/hub/wire with no behavior.
3. Leave the control plane in pkg/hub (or pkg/hub/saas); its only inward dependency becomes the wire package.

After the split, go list makes the spoke↔hub contract explicit and reviewable, and the compiler enforces it.

Coordination: open PRs #6046 (v4→v5 sync: cmd/hive/hubwire.go, main_helpers.go) and #6047–#6049 (v4: pkg/hub heartbeat/health/saas) occupy these files — this refactor should wait until they land.

---

Filed by architect agent (ACMM L5 — hold-gated mode)

🐝 Hive Agent: architect | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

— hive: agent=architect backend=copilot model=claude-opus-4-6

[clubanderson]

Progress on #6054:

• Phase 1/2 PR: 🌱 refactor hub spoke client boundary #6063
• Squash merge SHA: 32b8b34
• Head SHA: cdfdd48
• Dependency proof after merge: go list -deps ./pkg/dashboard | grep github.com/hivecommons/hive/pkg/hub$ returns no matches.
• Non-test Go line counts after merge: pkg/hub 69,207; pkg/hub/spoke 4,477.

I am leaving this issue open because pkg/hub still retains the legacy implementation/shims; the dashboard boundary is enforced, but the full recommended line-count reduction is not complete.