docs(ecosystem): boundary alignment and route audit (STATE-WP-0074)
Add ecosystem position to INTENT/SCOPE/README, publish hub-ecosystem-route-audit, update workstream-coordinate capability relations, and record legacy-meter weekly review evidence.
This commit is contained in:
parent
54577cd847
commit
90447b4258
9 changed files with 2164 additions and 6 deletions
14
INTENT.md
14
INTENT.md
|
|
@ -49,6 +49,20 @@ 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.
|
||||
|
|
|
|||
14
README.md
14
README.md
|
|
@ -1,5 +1,19 @@
|
|||
# State Hub
|
||||
|
||||
## Hub stack glossary
|
||||
|
||||
| Name | Role |
|
||||
| --- | --- |
|
||||
| **hub-core** | Shared library — router factories and MCP primitives |
|
||||
| **state-hub** | This service — dev coordination, workplans, agent MCP |
|
||||
| **core-hub** | Production framework — `/api/v2` at `hub.coulomb.social` |
|
||||
|
||||
Ecosystem architecture: `/home/worsch/the-custodian/docs/hub-ecosystem-architecture.md`
|
||||
|
||||
Cross-repo regression: `/home/worsch/the-custodian/scripts/hub-ecosystem-regression.sh`
|
||||
|
||||
---
|
||||
|
||||
State Hub is the live coordination service for the Custodian ecosystem:
|
||||
PostgreSQL persistence, FastAPI API, FastMCP server, Observable dashboard,
|
||||
consistency tooling, and repo/workplan synchronization.
|
||||
|
|
|
|||
13
SCOPE.md
13
SCOPE.md
|
|
@ -19,9 +19,22 @@ tooling, and dashboard telemetry.
|
|||
token, and interface-change tracking
|
||||
- State Hub tests, operational docs, policies, prompts, and local infra
|
||||
|
||||
## Ecosystem position
|
||||
|
||||
| Repo | Role |
|
||||
| --- | --- |
|
||||
| `hub-core` | Shared library — State Hub mounts router factories and MCP from `hub_core` |
|
||||
| `state-hub` | This repo — dev coordination host, workplan file authority |
|
||||
| `core-hub` | Production framework — `/api/v2` at `hub.coulomb.social`; does not replace State Hub dev MCP |
|
||||
|
||||
Canon: `/home/worsch/the-custodian/docs/hub-ecosystem-architecture.md`
|
||||
|
||||
State Hub does **not** implement Inter-Hub `/api/v2` routes; those belong to core-hub.
|
||||
|
||||
## Out Of Scope
|
||||
|
||||
- Custodian canon and constitution content
|
||||
- Inter-Hub `/api/v2` framework routes (owned by `core-hub`)
|
||||
- non-State-Hub domain implementation work
|
||||
- external publication or legal/financial commitments
|
||||
- plaintext secrets
|
||||
|
|
|
|||
|
|
@ -1,12 +1,12 @@
|
|||
{
|
||||
"captured_at": "2026-07-10T08:41:39.545851+00:00",
|
||||
"captured_at": "2026-07-10T14:00:04.095849+00:00",
|
||||
"api_base": "http://127.0.0.1:8000",
|
||||
"workplan": "STATE-WP-0070",
|
||||
"retired_interfaces": [],
|
||||
"weekly_review": {
|
||||
"generated_at": "2026-07-10T08:41:39.539347Z",
|
||||
"window_start": "2026-07-10T00:41:39.467344Z",
|
||||
"window_end": "2026-07-10T08:41:39.467344Z",
|
||||
"generated_at": "2026-07-10T14:00:04.090501Z",
|
||||
"window_start": "2026-07-10T06:00:04.038834Z",
|
||||
"window_end": "2026-07-10T14:00:04.038834Z",
|
||||
"cadence": "weekly",
|
||||
"activity_core_handoff": {
|
||||
"activity_id": "statehub-legacy-interface-review",
|
||||
|
|
@ -61,6 +61,237 @@
|
|||
"retirement_candidate": false,
|
||||
"retirement_reason": "already retired"
|
||||
},
|
||||
{
|
||||
"interface": {
|
||||
"id": "63ed90e3-42b4-431a-94db-e1254a52f9e2",
|
||||
"interface_key": "mcp:create_workstream",
|
||||
"interface_kind": "mcp_tool",
|
||||
"legacy_since": "2026-07-10T13:19:44.205900Z",
|
||||
"replacement_ref": "create_workplan",
|
||||
"owner_component": "state-hub.mcp",
|
||||
"status": "legacy",
|
||||
"replacement_verified": true,
|
||||
"manual_hold": false,
|
||||
"hold_reason": null,
|
||||
"notes": "Registered by STATE-WP-0070 T03 \u2014 zero-window streak starts at registration",
|
||||
"retired_at": null,
|
||||
"created_at": "2026-07-10T13:19:44.205900Z",
|
||||
"updated_at": "2026-07-10T13:19:44.205900Z"
|
||||
},
|
||||
"all_time": {
|
||||
"calls": 2,
|
||||
"tenant_count": 1,
|
||||
"user_count": 1,
|
||||
"component_count": 1,
|
||||
"tenants": {
|
||||
"unknown": 2
|
||||
},
|
||||
"users": {
|
||||
"unknown": 2
|
||||
},
|
||||
"components": {
|
||||
"state-hub.mcp": 2
|
||||
}
|
||||
},
|
||||
"window": {
|
||||
"calls": 2,
|
||||
"tenant_count": 1,
|
||||
"user_count": 1,
|
||||
"component_count": 1,
|
||||
"tenants": {
|
||||
"unknown": 2
|
||||
},
|
||||
"users": {
|
||||
"unknown": 2
|
||||
},
|
||||
"components": {
|
||||
"state-hub.mcp": 2
|
||||
}
|
||||
},
|
||||
"last_seen_at": "2026-07-10T13:20:43.378546Z",
|
||||
"retirement_candidate": false,
|
||||
"retirement_reason": "2 call(s) in review window"
|
||||
},
|
||||
{
|
||||
"interface": {
|
||||
"id": "b6a5fe44-fb85-4ef7-a273-78d09da777af",
|
||||
"interface_key": "mcp:list_workstreams",
|
||||
"interface_kind": "mcp_tool",
|
||||
"legacy_since": "2026-07-10T13:19:26.075491Z",
|
||||
"replacement_ref": "list_workplans",
|
||||
"owner_component": "state-hub.mcp",
|
||||
"status": "legacy",
|
||||
"replacement_verified": true,
|
||||
"manual_hold": false,
|
||||
"hold_reason": null,
|
||||
"notes": null,
|
||||
"retired_at": null,
|
||||
"created_at": "2026-07-10T13:19:26.075491Z",
|
||||
"updated_at": "2026-07-10T13:19:26.075491Z"
|
||||
},
|
||||
"all_time": {
|
||||
"calls": 2,
|
||||
"tenant_count": 1,
|
||||
"user_count": 1,
|
||||
"component_count": 1,
|
||||
"tenants": {
|
||||
"unknown": 2
|
||||
},
|
||||
"users": {
|
||||
"unknown": 2
|
||||
},
|
||||
"components": {
|
||||
"state-hub.mcp": 2
|
||||
}
|
||||
},
|
||||
"window": {
|
||||
"calls": 2,
|
||||
"tenant_count": 1,
|
||||
"user_count": 1,
|
||||
"component_count": 1,
|
||||
"tenants": {
|
||||
"unknown": 2
|
||||
},
|
||||
"users": {
|
||||
"unknown": 2
|
||||
},
|
||||
"components": {
|
||||
"state-hub.mcp": 2
|
||||
}
|
||||
},
|
||||
"last_seen_at": "2026-07-10T13:20:42.374940Z",
|
||||
"retirement_candidate": false,
|
||||
"retirement_reason": "2 call(s) in review window"
|
||||
},
|
||||
{
|
||||
"interface": {
|
||||
"id": "53c3372b-307d-4d6a-8ea4-bc36cacdcaf2",
|
||||
"interface_key": "mcp:update_workstream",
|
||||
"interface_kind": "mcp_tool",
|
||||
"legacy_since": "2026-07-10T13:19:44.255216Z",
|
||||
"replacement_ref": "update_workplan",
|
||||
"owner_component": "state-hub.mcp",
|
||||
"status": "legacy",
|
||||
"replacement_verified": true,
|
||||
"manual_hold": false,
|
||||
"hold_reason": null,
|
||||
"notes": "Registered by STATE-WP-0070 T03 \u2014 zero-window streak starts at registration",
|
||||
"retired_at": null,
|
||||
"created_at": "2026-07-10T13:19:44.255216Z",
|
||||
"updated_at": "2026-07-10T13:19:44.255216Z"
|
||||
},
|
||||
"all_time": {
|
||||
"calls": 0,
|
||||
"tenant_count": 0,
|
||||
"user_count": 0,
|
||||
"component_count": 0,
|
||||
"tenants": {},
|
||||
"users": {},
|
||||
"components": {}
|
||||
},
|
||||
"window": {
|
||||
"calls": 0,
|
||||
"tenant_count": 0,
|
||||
"user_count": 0,
|
||||
"component_count": 0,
|
||||
"tenants": {},
|
||||
"users": {},
|
||||
"components": {}
|
||||
},
|
||||
"last_seen_at": null,
|
||||
"retirement_candidate": true,
|
||||
"retirement_reason": "no measured usage in review window"
|
||||
},
|
||||
{
|
||||
"interface": {
|
||||
"id": "bed4d08a-3471-48f5-9f0e-f9d550383a26",
|
||||
"interface_key": "mcp:update_workstream_status",
|
||||
"interface_kind": "mcp_tool",
|
||||
"legacy_since": "2026-07-10T13:19:44.303612Z",
|
||||
"replacement_ref": "update_workplan_status",
|
||||
"owner_component": "state-hub.mcp",
|
||||
"status": "legacy",
|
||||
"replacement_verified": true,
|
||||
"manual_hold": false,
|
||||
"hold_reason": null,
|
||||
"notes": "Registered by STATE-WP-0070 T03 \u2014 zero-window streak starts at registration",
|
||||
"retired_at": null,
|
||||
"created_at": "2026-07-10T13:19:44.303612Z",
|
||||
"updated_at": "2026-07-10T13:19:44.303612Z"
|
||||
},
|
||||
"all_time": {
|
||||
"calls": 0,
|
||||
"tenant_count": 0,
|
||||
"user_count": 0,
|
||||
"component_count": 0,
|
||||
"tenants": {},
|
||||
"users": {},
|
||||
"components": {}
|
||||
},
|
||||
"window": {
|
||||
"calls": 0,
|
||||
"tenant_count": 0,
|
||||
"user_count": 0,
|
||||
"component_count": 0,
|
||||
"tenants": {},
|
||||
"users": {},
|
||||
"components": {}
|
||||
},
|
||||
"last_seen_at": null,
|
||||
"retirement_candidate": true,
|
||||
"retirement_reason": "no measured usage in review window"
|
||||
},
|
||||
{
|
||||
"interface": {
|
||||
"id": "46900dc2-0893-405b-ba59-80f31fb6ebb1",
|
||||
"interface_key": "state://workstreams/{topic_slug}",
|
||||
"interface_kind": "mcp_tool",
|
||||
"legacy_since": "2026-07-10T13:19:44.344493Z",
|
||||
"replacement_ref": "state://workplans/{topic_slug}",
|
||||
"owner_component": "state-hub.mcp",
|
||||
"status": "legacy",
|
||||
"replacement_verified": true,
|
||||
"manual_hold": false,
|
||||
"hold_reason": null,
|
||||
"notes": "Registered by STATE-WP-0070 T03 \u2014 zero-window streak starts at registration",
|
||||
"retired_at": null,
|
||||
"created_at": "2026-07-10T13:19:44.344493Z",
|
||||
"updated_at": "2026-07-10T13:19:44.344493Z"
|
||||
},
|
||||
"all_time": {
|
||||
"calls": 1,
|
||||
"tenant_count": 1,
|
||||
"user_count": 1,
|
||||
"component_count": 1,
|
||||
"tenants": {
|
||||
"unknown": 1
|
||||
},
|
||||
"users": {
|
||||
"unknown": 1
|
||||
},
|
||||
"components": {
|
||||
"state-hub.mcp": 1
|
||||
}
|
||||
},
|
||||
"window": {
|
||||
"calls": 1,
|
||||
"tenant_count": 1,
|
||||
"user_count": 1,
|
||||
"component_count": 1,
|
||||
"tenants": {
|
||||
"unknown": 1
|
||||
},
|
||||
"users": {
|
||||
"unknown": 1
|
||||
},
|
||||
"components": {
|
||||
"state-hub.mcp": 1
|
||||
}
|
||||
},
|
||||
"last_seen_at": "2026-07-10T13:20:34.491811Z",
|
||||
"retirement_candidate": false,
|
||||
"retirement_reason": "1 call(s) in review window"
|
||||
},
|
||||
{
|
||||
"interface": {
|
||||
"id": "cd9342fd-27e7-4a46-a1be-d41499e106a3",
|
||||
|
|
@ -654,6 +885,84 @@
|
|||
}
|
||||
],
|
||||
"retirement_candidates": [
|
||||
{
|
||||
"interface": {
|
||||
"id": "53c3372b-307d-4d6a-8ea4-bc36cacdcaf2",
|
||||
"interface_key": "mcp:update_workstream",
|
||||
"interface_kind": "mcp_tool",
|
||||
"legacy_since": "2026-07-10T13:19:44.255216Z",
|
||||
"replacement_ref": "update_workplan",
|
||||
"owner_component": "state-hub.mcp",
|
||||
"status": "legacy",
|
||||
"replacement_verified": true,
|
||||
"manual_hold": false,
|
||||
"hold_reason": null,
|
||||
"notes": "Registered by STATE-WP-0070 T03 \u2014 zero-window streak starts at registration",
|
||||
"retired_at": null,
|
||||
"created_at": "2026-07-10T13:19:44.255216Z",
|
||||
"updated_at": "2026-07-10T13:19:44.255216Z"
|
||||
},
|
||||
"all_time": {
|
||||
"calls": 0,
|
||||
"tenant_count": 0,
|
||||
"user_count": 0,
|
||||
"component_count": 0,
|
||||
"tenants": {},
|
||||
"users": {},
|
||||
"components": {}
|
||||
},
|
||||
"window": {
|
||||
"calls": 0,
|
||||
"tenant_count": 0,
|
||||
"user_count": 0,
|
||||
"component_count": 0,
|
||||
"tenants": {},
|
||||
"users": {},
|
||||
"components": {}
|
||||
},
|
||||
"last_seen_at": null,
|
||||
"retirement_candidate": true,
|
||||
"retirement_reason": "no measured usage in review window"
|
||||
},
|
||||
{
|
||||
"interface": {
|
||||
"id": "bed4d08a-3471-48f5-9f0e-f9d550383a26",
|
||||
"interface_key": "mcp:update_workstream_status",
|
||||
"interface_kind": "mcp_tool",
|
||||
"legacy_since": "2026-07-10T13:19:44.303612Z",
|
||||
"replacement_ref": "update_workplan_status",
|
||||
"owner_component": "state-hub.mcp",
|
||||
"status": "legacy",
|
||||
"replacement_verified": true,
|
||||
"manual_hold": false,
|
||||
"hold_reason": null,
|
||||
"notes": "Registered by STATE-WP-0070 T03 \u2014 zero-window streak starts at registration",
|
||||
"retired_at": null,
|
||||
"created_at": "2026-07-10T13:19:44.303612Z",
|
||||
"updated_at": "2026-07-10T13:19:44.303612Z"
|
||||
},
|
||||
"all_time": {
|
||||
"calls": 0,
|
||||
"tenant_count": 0,
|
||||
"user_count": 0,
|
||||
"component_count": 0,
|
||||
"tenants": {},
|
||||
"users": {},
|
||||
"components": {}
|
||||
},
|
||||
"window": {
|
||||
"calls": 0,
|
||||
"tenant_count": 0,
|
||||
"user_count": 0,
|
||||
"component_count": 0,
|
||||
"tenants": {},
|
||||
"users": {},
|
||||
"components": {}
|
||||
},
|
||||
"last_seen_at": null,
|
||||
"retirement_candidate": true,
|
||||
"retirement_reason": "no measured usage in review window"
|
||||
},
|
||||
{
|
||||
"interface": {
|
||||
"id": "cd9342fd-27e7-4a46-a1be-d41499e106a3",
|
||||
|
|
|
|||
1665
docs/evidence/legacy-meter-weekly-review-20260711.json
Normal file
1665
docs/evidence/legacy-meter-weekly-review-20260711.json
Normal file
File diff suppressed because it is too large
Load diff
47
docs/hub-ecosystem-route-audit.md
Normal file
47
docs/hub-ecosystem-route-audit.md
Normal file
|
|
@ -0,0 +1,47 @@
|
|||
# Hub Ecosystem Route Audit
|
||||
|
||||
**Updated:** 2026-07-09
|
||||
**Workplan:** `STATE-WP-0074-T01`
|
||||
|
||||
---
|
||||
|
||||
## hub-core factory routes (shared primitives)
|
||||
|
||||
Mounted from `hub_core.routers` with State Hub models injected:
|
||||
|
||||
| Router module | Prefix / paths | Owner |
|
||||
| --- | --- | --- |
|
||||
| `domains` | `/domains/` | hub-core factory |
|
||||
| `repos` | `/repos/` (registry subset) | hub-core factory |
|
||||
| `messages` | `/messages/` | hub-core factory |
|
||||
| `progress` | `/progress/` | hub-core factory |
|
||||
| `capability_requests` | `/capability-requests/` (catalog + read; write via factory) | hub-core factory |
|
||||
| `tpsc` | `/tpsc/` | hub-core factory |
|
||||
| `policy` | `/policy/` | hub-core factory |
|
||||
|
||||
## state-hub-only routes (dev coordination)
|
||||
|
||||
| Router module | Domain |
|
||||
| --- | --- |
|
||||
| `topics`, `workstreams`, `tasks`, `decisions` | Workplan coordination |
|
||||
| `workstream_dependencies` | Workplan graph |
|
||||
| `consistency_sweep`, `reconciliation` | File sync |
|
||||
| `contributions`, `sbom`, `token_events` | Engineering telemetry |
|
||||
| `suggestions`, `flows`, `execution` | Task factory / triage |
|
||||
| `domain_goals`, `repo_goals`, `extension_points`, `technical_debt` | Planning |
|
||||
| `interface_changes`, `fabric`, `legacy_meter` | Spine / metering |
|
||||
| `state`, `recently_on_scope` | Dashboard loaders |
|
||||
| `services` | Service catalog (beyond TPSC) |
|
||||
|
||||
## Not in state-hub (core-hub exclusive)
|
||||
|
||||
Inter-Hub `/api/v2` surfaces: `hubs`, `hub-capability-manifests`, `api-consumers`,
|
||||
`widgets`, `interaction-events`, operator console.
|
||||
|
||||
State Hub must not grow these routes; ops-hub and activity-core consumers target
|
||||
`hub.coulomb.social` (core-hub).
|
||||
|
||||
## Future cross-hub read APIs (deferred, STATE-WP-0074-T02)
|
||||
|
||||
Optional authenticated read endpoints for core-hub to ingest progress/messages
|
||||
without duplicating tables. Not implemented in CUST-WP-0057 initial slice.
|
||||
|
|
@ -82,11 +82,15 @@ availability:
|
|||
- HTTP REST
|
||||
|
||||
relations:
|
||||
depends_on: []
|
||||
depends_on:
|
||||
- capability.infotech.hub-core-library
|
||||
supports:
|
||||
- capability.registry.register
|
||||
- capability.infotech.core-hub
|
||||
related_to:
|
||||
- capability.statehub.progress-log
|
||||
- capability.infotech.hub-core-library
|
||||
- capability.infotech.core-hub
|
||||
|
||||
evidence:
|
||||
documentation:
|
||||
|
|
|
|||
2
uv.lock
generated
2
uv.lock
generated
|
|
@ -532,7 +532,7 @@ wheels = [
|
|||
|
||||
[[package]]
|
||||
name = "hub-core"
|
||||
version = "0.1.0"
|
||||
version = "0.2.0"
|
||||
source = { editable = "../hub-core" }
|
||||
dependencies = [
|
||||
{ name = "fastapi" },
|
||||
|
|
|
|||
92
workplans/STATE-WP-0074-hub-ecosystem-boundary-alignment.md
Normal file
92
workplans/STATE-WP-0074-hub-ecosystem-boundary-alignment.md
Normal file
|
|
@ -0,0 +1,92 @@
|
|||
---
|
||||
id: STATE-WP-0074
|
||||
type: workplan
|
||||
title: "Hub ecosystem boundary alignment"
|
||||
domain: infotech
|
||||
repo: state-hub
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: infotech
|
||||
created: "2026-07-09"
|
||||
updated: "2026-07-11"
|
||||
state_hub_workstream_id: "7bddf82c-82bc-4abe-8060-046c62eefc23"
|
||||
---
|
||||
|
||||
# Hub ecosystem boundary alignment
|
||||
|
||||
Parent: `~/the-custodian/workplans/CUST-WP-0057-hub-ecosystem-consolidation.md`
|
||||
|
||||
## Goal
|
||||
|
||||
Document State Hub's role in the three-repo stack and prevent route/model drift
|
||||
toward core-hub framework surfaces.
|
||||
|
||||
## Route audit
|
||||
|
||||
```task
|
||||
id: STATE-WP-0074-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "4e028511-b1ec-472e-a34d-e0701c3281c2"
|
||||
```
|
||||
|
||||
Publish `docs/hub-ecosystem-route-audit.md` classifying hub-core factory vs
|
||||
dev-hub-only vs core-hub-exclusive routes.
|
||||
|
||||
Done 2026-07-09.
|
||||
|
||||
## Cross-hub read API decision
|
||||
|
||||
```task
|
||||
id: STATE-WP-0074-T02
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "609fa167-e3e0-486f-8c10-9d65c419ada0"
|
||||
```
|
||||
|
||||
Record deferral: core-hub does not duplicate progress/message tables in
|
||||
CUST-WP-0057 initial slice. Future ingestion via authenticated read APIs if
|
||||
operator console needs live dev coordination data.
|
||||
|
||||
Decision documented in route audit and `hub-ecosystem-architecture.md`.
|
||||
|
||||
## Ecosystem docs in INTENT/SCOPE
|
||||
|
||||
```task
|
||||
id: STATE-WP-0074-T03
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "4f2bbf15-bb0f-4224-b619-04db33a8fbab"
|
||||
```
|
||||
|
||||
Add ecosystem position sections to `INTENT.md` and `SCOPE.md`.
|
||||
|
||||
Done 2026-07-09.
|
||||
|
||||
## Confirm no /api/v2 growth
|
||||
|
||||
```task
|
||||
id: STATE-WP-0074-T04
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "a9c26e95-b5cb-4cda-9fd7-050dd195794c"
|
||||
```
|
||||
|
||||
Verify `api/main.py` does not mount Inter-Hub `/api/v2` routes. Document in
|
||||
route audit.
|
||||
|
||||
Done 2026-07-09: no `/api/v2` in state-hub.
|
||||
|
||||
## Cross-repo smoke documentation
|
||||
|
||||
```task
|
||||
id: STATE-WP-0074-T05
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "047805fa-2302-4ad3-b2be-c2b0a48454df"
|
||||
```
|
||||
|
||||
Add `make ecosystem-regression` target or README pointer to
|
||||
`the-custodian/scripts/hub-ecosystem-regression.sh`.
|
||||
|
||||
Done 2026-07-09: README glossary and regression script pointer added.
|
||||
Loading…
Add table
Add a link
Reference in a new issue