5.4 KiB
| domain | repo | updated |
|---|---|---|
| custodian | state-hub | 2026-05-17 |
INTENT
This file explains why State Hub exists, where its authority begins and ends, and why it is now separate from the-custodian.
Retirement status
State Hub is a legacy service in active retirement planning. It remains operational during the migration, but it is not the target home for new cross-domain capabilities.
The replacement program is coordinated in
/home/worsch/prj-state-hub-retirement, whose GOAL.md defines the migration
and retirement gates. Repository representation, file-backed record indexing,
consistency reconciliation, and governed repository changes are moving toward
/home/worsch/repo-manager. Cross-domain identity, communication, interaction,
state projections, telemetry, and domain-extension composition are moving
toward the consolidated hub-core framework.
Until the retirement gates are met, State Hub remains authoritative only where the current contracts and repository-backed workflows require it. Changes made during this period should preserve compatibility, enable extraction, reduce scope, or address operational risk; they should not establish new permanent architectural ownership here.
Why it exists
State Hub exists because the Custodian ecosystem needs a live, queryable, auditable memory of work: domains, repositories, workstreams, tasks, decisions, progress events, lifecycle state, and operational telemetry.
Files are excellent for canon, workplans, and provenance. They are less ergonomic as the live coordination surface for agents, dashboards, API clients, and cross-repo automation. State Hub gives those actors a local-first service that can answer "what is happening now?" without replacing the governance record that lives in the-custodian.
The governing principle
State Hub is the readable state and coordination service for the ecosystem.
It should answer:
- What exists? Domains, repos, workstreams, tasks, decisions, and tools.
- What changed? Progress events, lifecycle events, interface changes, and synchronization results.
- What needs attention? Blockers, human interventions, repo health, and dashboard-visible drift.
It should not become the canon, the task factory, the identity authority, or a general application platform. When State Hub detects facts, it records and exposes them; when new work must be spawned from events, that responsibility belongs to activity-core or a human-approved workflow.
Sanctioned writes (STATE-WP-0061): besides resolve_decision and progress
events, the hub may persist gated needs as Suggestion records, bump demand
relevance, vet/decline/promote them into real tasks, and project WSJF ranking
as a read model for daily triage.
Ecosystem position
State Hub is the dev coordination layer in the three-repo hub stack:
| Repo | Role |
|---|---|
hub-core |
Shared library imported by State Hub |
state-hub |
This service — workplans, tasks, dev MCP |
core-hub |
Production framework at hub.coulomb.social |
Canon: /home/worsch/the-custodian/docs/hub-ecosystem-architecture.md
What it is
State Hub is the local-first operational state service for Custodian.
It contains:
- PostgreSQL persistence and Alembic migrations
- FastAPI endpoints for topics, repos, workstreams, tasks, decisions, progress, capabilities, contributions, SBOM, TPSC, and related coordination records
- FastMCP tools for agent access
- Observable dashboard pages for human inspection
- consistency tooling that syncs repo-backed workplan files into live state
- task-flow evaluation and policies for lifecycle movement
- operational docs, tests, local infra, and prompts for running the service
What it is not
| Concern | Owner |
|---|---|
| Canon, values, constitution, and domain charters | the-custodian |
| Event-triggered maintenance task creation | activity-core |
| General task lifecycle backend outside Custodian workplans | issue-core |
| Repository capability profiling and SCOPE generation | repo-scoping |
| Network connectivity/tunnel management | ops-bridge |
| External publication, contracts, payments, or legal authority | Human approval only |
State Hub can reference these systems and expose their status, but it should not absorb their core responsibilities.
What it enables
When State Hub is doing its job, Bernd and agents can:
- start a session with current cross-domain state instead of stale local memory
- see active workstreams, tasks, blockers, decisions, and recent progress in one place
- sync workplan files into database-backed dashboard views without ghost workstreams
- access the same coordination state through REST, MCP, CLI, and dashboard
- keep operational state local, inspectable, and recoverable
Design values
Local-first operations. The service runs on local infrastructure and binds to loopback by default.
Files remain authoritative where they should. Repo-backed workplans are written as files first, then synchronized into the database.
Append-only progress. Progress events record what happened and are not silently rewritten.
Degrade gracefully. The dashboard and tools should make partial state visible rather than fail opaquely when one component is unavailable.
Narrow authority. State Hub coordinates and exposes state; it does not make irreversible human decisions or become the owner of every adjacent system.