docs(ecosystem): complete hub stack consolidation (CUST-WP-0057)

Publish ecosystem architecture, event mapping, capability bridge, and async-base decision docs; add cross-repo regression script; update extraction boundary and bootstrap status; archive WP-0058 touch-ups.
2026-07-11 01:26:53 +02:00 · 2026-07-11 01:26:53 +02:00 · aab187937b
commit aab187937b
parent 10d691886d
9 changed files with 717 additions and 11 deletions
--- a/docs/fos-hub-bootstrap-sequence-status.md
+++ b/docs/fos-hub-bootstrap-sequence-status.md
@ -1,6 +1,6 @@
 # FOS Hub Bootstrap Sequence Status

-Updated: 2026-07-08
+Updated: 2026-07-09

 ## Purpose

@ -24,6 +24,7 @@ Do not restart FOS bootstrap at the old `NK-WP-0001` Keycloak path. That workpla
 | Ops hub / Core Hub | T13–T18 done; T16 deployed evidence and T17 cutover coupling closed 2026-07-08. Production serves Core Hub at `hub.coulomb.social` since 2026-07-03. | Monitor `CORE-WP-0007` stabilization window; Haskell retirement is operator-gated rollback cleanup only. |
 | Legacy Inter-Hub | `CUST-WP-0047-T05` and `CUST-WP-0049-T06` superseded 2026-07-03. | Rollback-only; do not request new Inter-Hub operator keys. |
 | Fin hub/business | T20–T23 done (canon + fin-hub scaffold + models). T24–T26 remain open. | Implement cost ingestion, runway calculator, cross-hub coupling, and pricing/legal packaging. |
+| Hub ecosystem alignment | `CUST-WP-0057` active — architecture doc, hub-core utils adoption in core-hub, boundary workplans. | Execute `HUB-WP-0003`, `CORE-WP-0009`, `STATE-WP-0074`; run `scripts/hub-ecosystem-regression.sh`. |

 ## Stable Pickup Order

--- a/docs/hub-core-extraction-boundary.md
+++ b/docs/hub-core-extraction-boundary.md
@ -245,11 +245,20 @@ to import it:
 5. `cd /home/worsch/state-hub && make test` remains green before and after the
   editable `hub-core` dependency is introduced.

+## Ecosystem composition (CUST-WP-0057)
+
+hub-core is the **library layer** only. It does not own:
+
+- core-hub framework tables (`hubs`, `widgets`, `hub_capability_manifests`, …)
+- state-hub dev-hub tables (workplans, tasks, topics, …)
+
+Integration canon: `docs/hub-ecosystem-architecture.md`
+
 ## Next Step

-**CUST-WP-0048** is finished; **CUST-WP-0025-T08** is done. Proceed to Phase 2
-dev-hub rename (**CUST-WP-0025-T09+**): MCP server name, config migration, and
-integration-point renames. Optional follow-up extractions (not blocking rename):
+**CUST-WP-0048** is finished; **CUST-WP-0025-T08** is done. Ecosystem
+consolidation continues under **CUST-WP-0057** (compose hub-core, state-hub,
+core-hub without merging repos). Optional follow-up extractions:

 - map State Hub `ProgressEvent` foreign keys into `subject_refs`
 - map CapabilityRequest workplan/task columns into JSON context fields
--- a/docs/hub-ecosystem-architecture.md
+++ b/docs/hub-ecosystem-architecture.md
@ -0,0 +1,105 @@
+# Hub Ecosystem Architecture
+
+**Updated:** 2026-07-09  
+**Workplan:** `CUST-WP-0057`  
+**Status:** Active decision record
+
+---
+
+## Purpose
+
+Define how `hub-core`, `state-hub`, and `core-hub` compose into one FOS hub
+stack. This document resolves naming confusion and entity ownership without
+merging repositories.
+
+---
+
+## Three-layer model
+
+| Layer | Repo | Role | Production URL |
+| --- | --- | --- | --- |
+| **Library** | `hub-core` | Shared models, schemas, router factories, MCP wrapper, utils | None — pip/uv import only |
+| **Dev coordination** | `state-hub` | File-first workplans, tasks, decisions, consistency sync, dev MCP | Local / operator (`127.0.0.1:8000`) |
+| **Production framework** | `core-hub` | Inter-Hub successor: hubs, manifests, widgets, `/api/v2`, operator console | `hub.coulomb.social` |
+
+```text
+                    ┌─────────────────┐
+                    │    core-hub     │  Production framework (/api/v2)
+                    │  (async service)│
+                    └────────┬────────┘
+                             │ imports utils; HTTP bridge to dev data (future)
+              ┌──────────────┼──────────────┐
+              ▼              ▼              ▼
+       ┌────────────┐  ┌────────────┐  ┌────────────┐
+       │  hub-core  │◄─│ state-hub  │  │  ops-hub   │
+       │  (library) │  │ (dev host) │  │ (consumer) │
+       └────────────┘  └────────────┘  └────────────┘
+```
+
+---
+
+## Naming glossary
+
+| Name | What it is | What it is not |
+| --- | --- | --- |
+| **hub-core** | Python package `hub_core` — library boundary | A running hub service |
+| **core-hub** | Production interaction framework service | The shared library |
+| **state-hub** | Dev coordination host (State Hub / dev-hub) | The Inter-Hub `/api/v2` framework |
+
+Mnemonic: **hub-core** = core *primitives*; **core-hub** = core *framework runtime*.
+
+---
+
+## Canonical entity ownership
+
+| Entity family | Canonical owner | Notes |
+| --- | --- | --- |
+| `domains`, `managed_repos` (registry) | `hub-core` models; `state-hub` host | core-hub uses `hubs` table — see capability bridge doc |
+| `agent_messages` | `hub-core` + `state-hub` | core-hub does not duplicate; reads via State Hub API when needed |
+| `progress_events` | `hub-core` + `state-hub` | Dev coordination audit trail |
+| `interaction_events` | `core-hub` | Widget-scoped ops evidence (`/api/v2/interaction-events`) |
+| `capability_catalog`, `capability_requests` | `hub-core` + `state-hub` | Maturity and workflow lane |
+| `hub_capability_manifests` | `core-hub` | Inter-Hub manifest contract |
+| `hubs`, `widgets`, `api_consumers`, `api_keys` | `core-hub` | Framework registry only |
+| `workplans`, `tasks`, `decisions` | `state-hub` | File-first authority; core-hub may index later |
+| `tpsc_*`, policy documents | `hub-core` + `state-hub` | core-hub references evidence, does not reimplement |
+| Slug/pagination/path utils | `hub-core` | All hosts import; no local duplicates |
+
+---
+
+## Governing decisions
+
+1. **Compose, do not merge** — three repos remain; shared code moves into `hub-core`.
+2. **hub-core stays a library** — no `uvicorn` entrypoint, no K8s manifests.
+3. **core-hub owns `/api/v2`** — Inter-Hub compatibility is non-negotiable for ops-hub and activity-core.
+4. **state-hub owns dev coordination** — workplan files remain source of truth until a recorded ADR says otherwise.
+5. **Separate SQLAlchemy metadata** — each runtime keeps its own `Base`; router factories inject host models.
+6. **Incremental adoption** — core-hub adopts hub-core utilities first; framework models stay local.
+
+---
+
+## Integration contracts
+
+| From | To | Mechanism | Status |
+| --- | --- | --- | --- |
+| `state-hub` | `hub-core` | Editable package import | Done (`CUST-WP-0048`) |
+| `core-hub` | `hub-core` | Editable package import (utils) | In progress (`CORE-WP-0009`) |
+| `core-hub` | `state-hub` | HTTP read APIs for progress/messages | Deferred (`STATE-WP-0070`) |
+| `ops-hub` | `core-hub` | `/api/v2` bootstrap | Production |
+| Agents | `state-hub` | dev-hub MCP | Production |
+| Operators | `core-hub` | Operator CLI + console | Production |
+
+See also:
+
+- `hub-ecosystem-event-mapping.md` — progress vs interaction events
+- `hub-ecosystem-capability-bridge.md` — catalog vs manifest IDs
+- `hub-core-extraction-boundary.md` — library extraction history
+
+---
+
+## Non-goals
+
+- Renaming `hub-core` or `core-hub` repositories
+- Moving State Hub workplan tables into core-hub in this lane
+- Replacing core-hub `/api/v2` with state-hub routes
+- Publishing hub-core to public PyPI (path/editable deps remain fine)
--- a/docs/hub-ecosystem-async-base-decision.md
+++ b/docs/hub-ecosystem-async-base-decision.md
@ -0,0 +1,32 @@
+# Hub Ecosystem — Async SQLAlchemy Base Decision
+
+**Updated:** 2026-07-09  
+**Workplan:** `HUB-WP-0003-T04`  
+**Decision:** Defer shared async base; hosts keep separate metadata
+
+---
+
+## Question
+
+Should `hub_core.models.base` expose an async-compatible declarative base for
+core-hub (async SQLAlchemy) while state-hub remains on sync sessions?
+
+---
+
+## Finding
+
+- `state-hub` uses sync SQLAlchemy with FastAPI dependency-injected sessions.
+- `core-hub` uses `sqlalchemy.ext.asyncio` with a separate `core_hub.db.Base`.
+- Router factories in hub-core accept **host-injected models** — they do not
+  require a shared metadata registry across runtimes.
+- Merging bases would couple migration ownership and risk breaking State Hub's
+  400+ test regression without benefit for the first consolidation slice.
+
+---
+
+## Decision
+
+**Defer.** Each runtime keeps its own `Base` and Alembic history. hub-core
+documents metadata isolation in `docs/metadata-isolation.md`. Revisit only if
+a second async host needs to mount hub-core router factories with shared tables
+in the same database instance.
--- a/docs/hub-ecosystem-capability-bridge.md
+++ b/docs/hub-ecosystem-capability-bridge.md
@ -0,0 +1,91 @@
+# Hub Ecosystem Capability Bridge
+
+**Updated:** 2026-07-09  
+**Workplan:** `CUST-WP-0057-T07`
+
+---
+
+## Purpose
+
+Map reuse-surface capability IDs to State Hub catalog rows and Core Hub
+`hub_capability_manifests` without inventing parallel naming schemes.
+
+---
+
+## Three representations
+
+| Representation | Location | Identifier | Purpose |
+| --- | --- | --- | --- |
+| **Reuse-surface registry** | `registry/capabilities/*.md` + federation index | `capability.<domain>.<name>` | Discovery, maturity, consumer guidance |
+| **State Hub catalog** | `capability_catalog` table | UUID row + `capability_type` + `title` | Dev workflow, requests, maturity tracking |
+| **Core Hub manifest** | `hub_capability_manifests` table | UUID row + `body_json` | Inter-Hub `/api/v2` bootstrap, widget activation |
+
+These are complementary, not duplicates of the same row.
+
+---
+
+## Worked example: hub stack capabilities
+
+### `capability.infotech.hub-core-library`
+
+| Field | Value |
+| --- | --- |
+| Registry owner | `hub-core` |
+| State Hub catalog | Optional row with `capability_type=library`, linked to `hub-core` repo |
+| Core Hub manifest | Not required — library is not a deployed hub |
+
+### `capability.infotech.core-hub`
+
+| Field | Value |
+| --- | --- |
+| Registry owner | `core-hub` |
+| State Hub catalog | Row referencing `core-hub` managed repo |
+| Core Hub manifest | Activated manifest for `hubSlug=core-hub` with widgets for ops evidence |
+
+**Manifest `body_json` should include:**
+
+```json
+{
+  "reuseSurfaceId": "capability.infotech.core-hub",
+  "manifestVersion": "0.1.0",
+  "capabilities": []
+}
+```
+
+### `capability.statehub.workstream-coordinate` (if registered)
+
+| Field | Value |
+| --- | --- |
+| Registry owner | `state-hub` |
+| State Hub catalog | Native — describes the dev coordination service |
+| Core Hub manifest | None — state-hub is not an Inter-Hub framework hub |
+
+---
+
+## Bridge rules
+
+1. **Registry ID is the stable public name** — manifests and catalog rows reference it in JSON metadata.
+2. **Catalog rows are dev-lane** — maturity, disputes, requests, WSJF triage live in State Hub.
+3. **Manifests are ops-lane** — bootstrap, API consumers, widgets, interaction events live in Core Hub.
+4. **Activation does not copy secrets** — API key material stays hash/prefix only in Core Hub.
+5. **One reuse-surface ID per deployed hub** — ops-hub manifest references `capability.infotech.ops-hub` (when registered), not the core-hub library ID.
+
+---
+
+## Registration flow (recommended)
+
+```text
+1. Author capability.infotech.<name> in repo registry/
+2. State Hub: register repo + optional capability_catalog row citing reuseSurfaceId
+3. Core Hub: POST /api/v2/hub-capability-manifests with reuseSurfaceId in body
+4. Core Hub: activate manifest → widgets → interaction-events for ops evidence
+5. reuse-surface federation publish indexes maturity from registry files
+```
+
+---
+
+## Anti-patterns
+
+- Using `hub-core` manifest activation for a library that has no runtime widgets
+- Creating a second capability ID in manifest JSON that disagrees with reuse-surface
+- Storing full API keys in State Hub progress or catalog rows
--- a/docs/hub-ecosystem-event-mapping.md
+++ b/docs/hub-ecosystem-event-mapping.md
@ -0,0 +1,114 @@
+# Hub Ecosystem Event Mapping
+
+**Updated:** 2026-07-09  
+**Workplan:** `CUST-WP-0057-T06`
+
+---
+
+## Purpose
+
+Clarify when to use State Hub `ProgressEvent` vs Core Hub `InteractionEvent`,
+and how downstream consumers (activity-core, ops-hub) should interpret each.
+
+---
+
+## Event families
+
+| Family | Owner | Table | Typical producer | Typical consumer |
+| --- | --- | --- | --- | --- |
+| **Progress** | state-hub | `progress_events` | Agents, consistency sync, custodian operators | State Hub MCP, dashboard, audit |
+| **Interaction** | core-hub | `interaction_events` | ops-hub bootstrap, widget verification, operator CLI | activity-core sink, ops evidence |
+
+Both are append-oriented and must not contain secrets.
+
+---
+
+## ProgressEvent (dev coordination)
+
+**Schema owner:** `hub_core.models.progress_event` (library); State Hub extends with FKs.
+
+**Emit when:**
+
+- A workplan task status changes
+- An agent logs session progress (`POST /progress/`)
+- Consistency sync or reconciliation completes
+- A custodian operator records a milestone
+
+**Key fields:**
+
+- `event_type` — e.g. `note`, `milestone`, `risk`, `alert`
+- `summary` — human-readable one-liner
+- `detail` — JSON payload (non-secret)
+- `subject_refs` — generic JSON linking workplan_id, task_id, topic_id, repo_slug
+
+**Example `subject_refs`:**
+
+```json
+{
+  "workplan_id": "CUST-WP-0057",
+  "task_id": "CUST-WP-0057-T01",
+  "repo": "the-custodian"
+}
+```
+
+---
+
+## InteractionEvent (ops / framework evidence)
+
+**Schema owner:** `core_hub.models.InteractionEvent`
+
+**Emit when:**
+
+- ops-hub bootstrap verifies an endpoint (`ops-endpoint-verified`)
+- Operator CLI deployed smoke records widget activity
+- A widget emits framework-scoped evidence under `/api/v2/interaction-events`
+
+**Key fields:**
+
+- `widget_id` — FK to core-hub `widgets`
+- `event_type` — cataloged in `event-types` seed
+- `view_context`, `metadata_json`, `body_json`
+
+**Example body:**
+
+```json
+{
+  "hubSlug": "ops-hub",
+  "endpoint": "https://hub.coulomb.social/api/v2/hubs",
+  "status": "verified"
+}
+```
+
+---
+
+## Mapping rules
+
+| Situation | Use | Do not |
+| --- | --- | --- |
+| Agent closes a workplan task | `ProgressEvent` via State Hub | Duplicate as `InteractionEvent` |
+| ops-hub bootstrap smoke passes | `InteractionEvent` via Core Hub | POST to State Hub progress |
+| Cutover gate evaluation | `ProgressEvent` (custodian audit) + optional `InteractionEvent` (ops evidence) | Single combined table |
+| activity-core ingestion | `core-hub-interaction-event` sink for interaction family | Assume progress events appear in Core Hub DB |
+
+**Correlation:** When both families describe one operator action, use a shared
+non-secret `correlation_id` in `detail` (progress) and `metadata_json`
+(interaction). Do not dual-write the same semantic event to both tables.
+
+---
+
+## Consumer guidance
+
+### activity-core
+
+- Primary sink: Core Hub interaction events (`core-hub-interaction-event`)
+- State Hub progress remains fallback during transition (see `testing-release-and-migration.md`)
+
+### ops-hub
+
+- Bootstrap and gate probes target Core Hub `/api/v2`
+- Progress notes about bootstrap planning belong in State Hub
+
+### Agents (MCP)
+
+- Use State Hub `append_progress` for coordination work
+- Do not call Core Hub interaction-event APIs unless executing ops-widget workflows
--- a/scripts/hub-ecosystem-regression.sh
+++ b/scripts/hub-ecosystem-regression.sh
@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Cross-repo regression gate for CUST-WP-0057 hub ecosystem consolidation.
+set -euo pipefail
+
+HUB_CORE="${HUB_CORE_ROOT:-/home/worsch/hub-core}"
+STATE_HUB="${STATE_HUB_ROOT:-/home/worsch/state-hub}"
+CORE_HUB="${CORE_HUB_ROOT:-/home/worsch/core-hub}"
+
+run_pytest() {
+  local repo="$1"
+  local label="$2"
+  echo "==> ${label} (${repo})"
+  cd "${repo}"
+  if command -v uv >/dev/null 2>&1 && [[ -f pyproject.toml ]]; then
+    if [[ "${repo}" == *core-hub* ]]; then
+      uv sync --extra dev >/dev/null
+    fi
+    uv run python -m pytest -q
+  else
+    python3 -m pytest -q
+  fi
+}
+
+echo "Hub ecosystem regression gate"
+echo "hub-core:  ${HUB_CORE}"
+echo "state-hub: ${STATE_HUB}"
+echo "core-hub:  ${CORE_HUB}"
+echo
+
+run_pytest "${HUB_CORE}" "hub-core"
+run_pytest "${STATE_HUB}" "state-hub"
+run_pytest "${CORE_HUB}" "core-hub"
+
+echo
+echo "All hub ecosystem test suites passed."
--- a/workplans/CUST-WP-0057-hub-ecosystem-consolidation.md
+++ b/workplans/CUST-WP-0057-hub-ecosystem-consolidation.md
@ -0,0 +1,317 @@
+---
+id: CUST-WP-0057
+type: workplan
+title: "Hub ecosystem consolidation — hub-core, core-hub, state-hub alignment"
+domain: infotech
+repo: the-custodian
+status: finished
+owner: codex
+topic_slug: custodian
+created: "2026-07-09"
+updated: "2026-07-11"
+state_hub_workstream_id: "3a829663-1a36-4a48-a09e-aaf6cf26aaee"
+---
+
+# CUST-WP-0057 — Hub Ecosystem Consolidation
+
+## Goal
+
+Align `hub-core`, `core-hub`, and `state-hub` into a coherent three-layer hub
+stack with explicit boundaries, shared library reuse where it reduces drift, and
+documented integration contracts — without collapsing distinct runtime roles or
+breaking Core Hub production `/api/v2` consumers.
+
+This workplan supersedes ad hoc overlap between the Phase 2 library extraction
+(`hub-core`, `CUST-WP-0048`) and Phase 3 production framework (`core-hub`,
+`CUST-WP-0052`). It does **not** merge repos; it defines how they compose.
+
+## Overlap Map (current state)
+
+### Target layer model
+
+| Layer | Repo | Role | Runs in production? |
+| --- | --- | --- | --- |
+| Library | `hub-core` | Reusable models, schemas, router factories, MCP wrapper, migration scaffolds | No — imported by hosts |
+| Dev coordination | `state-hub` | File-first workplans, tasks, decisions, consistency sync, dashboard, dev MCP | Yes — local/operator dev hub |
+| Production framework | `core-hub` | Inter-Hub successor: hubs, manifests, widgets, interaction events, operator console, `/api/v2` | Yes — `hub.coulomb.social` |
+
+### Entity overlap matrix
+
+| Concern | hub-core | state-hub | core-hub | Overlap type | Consolidation stance |
+| --- | --- | --- | --- | --- | --- |
+| Domains / managed repos | `Domain`, `ManagedRepo` + router factories | Extended models + dev counts/onboarding | Not modeled (hub registry uses `Hub` entity) | Partial — registry vs framework hub | Keep hub-core primitives; map `Hub` ↔ domain/repo in integration doc |
+| Agent messages | `AgentMessage` + factory | Uses hub-core factory | Not implemented | Library-only today | core-hub ingests via State Hub API or future read-model bridge; do not duplicate table |
+| Progress events | `ProgressEvent` + `subject_refs` JSON | FK-extended model + hub-core factory | `InteractionEvent` (widget-scoped, different shape) | **Semantic** — both are append-only evidence | Treat as distinct event families; document mapping rules |
+| Capability catalog / requests | `CapabilityCatalog`, `CapabilityRequest` + factories | Dev workflow columns + hub-core factories | `HubCapabilityManifest` (Inter-Hub manifest contract) | **Conceptual** — catalog vs manifest | core-hub keeps manifest tables; state-hub keeps maturity catalog; link via capability IDs in integration contract |
+| TPSC / service catalog | Full models + router | hub-core factory | Not implemented | Library-only | state-hub remains host; core-hub references via HTTP/evidence, not reimplementation |
+| Policy lookup | Router factory + schemas | hub-core factory + local paths | `policy-scopes` catalog (static seed) | Partial | Share catalog YAML source or hub-core policy router where paths align |
+| Workplans / tasks / decisions | Out of scope (by design) | Canonical implementation | Spec-only (`workplan-coordination.md`); not persisted yet | **Boundary tension** | state-hub remains canonical until ADR records cutover; core-hub indexes/displays, does not fork tables |
+| Hubs / manifests / widgets / API consumers | Out of scope | Out of scope | Canonical (`/api/v2`) | None — core-hub exclusive | Do not move into hub-core |
+| MCP agent tools | `HubCoreMCPServer` (HTTP client to host API) | Composes hub-core + dev-hub tools | Operator CLI only | Partial | core-hub CLI for ops; agent MCP stays on state-hub for dev coordination |
+| Slug/pagination/utils | `hub_core.utils.*` | Uses hub-core | Local `slugify()` in `api/v2.py` | **Code duplication** | core-hub should import hub-core utils |
+| SQLAlchemy base / timestamps | `hub_core.models.base` | Mixed — some local, some via hub-core | `core_hub.db.Base` (separate metadata) | **Technical** — two bases | Document metadata isolation; optional shared base module in hub-core |
+| Auth / API keys | Out of scope | State Hub auth | `ApiConsumer`, `ApiKey` (hash/prefix only) | core-hub exclusive | No extraction to hub-core unless multi-hub auth factory is needed |
+
+### Drift risks (why consolidation is needed)
+
+1. **Parallel Python stacks** — core-hub rebuilt FastAPI/SQLAlchemy without depending on
+   hub-core, so shared concepts (slugs, pagination, message/progress shapes) can diverge.
+2. **Naming collision** — `hub-core` vs `core-hub` confuses agents and operators.
+3. **Unset coordination cutover** — core-hub `data-model.md` still asks whether workplan
+   tables move to Core Hub; without a decision, both repos may grow competing models.
+4. **Missing capability relations** — reuse-surface entries do not cross-link the three
+   repos, so federation discovery hides the intended stack.
+5. **Domain metadata mismatch** — hub-core INTENT says `inter_hub`; classifications say
+   `infotech`; core-hub is `infotech` interaction-framework.
+
+## Governing decisions (to lock in T01)
+
+- **hub-core stays a library** — no service entrypoint, no K8s, no production URL.
+- **core-hub stays the Inter-Hub production framework** — owns `/api/v2` compatibility.
+- **state-hub stays the dev coordination host** — owns workplan file authority and
+  consistency sync until an explicit ADR migrates that role.
+- **Consolidation means compose, not merge** — shared code moves into hub-core;
+  integration contracts define HTTP/MCP boundaries between runtimes.
+- **No big-bang cutover** — adopt hub-core in core-hub incrementally behind compatibility
+  tests; State Hub regression must stay green throughout.
+
+## Child / companion workplans
+
+| Repo | Workplan | Scope |
+| --- | --- | --- |
+| `hub-core` | `HUB-WP-0003-ecosystem-consolidation-library-lane.md` | Library extensions, utils export, capability relations, async base seam |
+| `core-hub` | `CORE-WP-0009-hub-core-adoption-and-integration.md` (create in T02) | hub-core dependency, utils adoption, integration contract implementation |
+| `state-hub` | `STATE-WP-0074-hub-ecosystem-boundary-alignment.md` (create in T03) | Boundary docs, cross-hub progress/message export APIs if needed |
+
+## Task: Publish ecosystem architecture decision
+
+```task
+id: CUST-WP-0057-T01
+status: done
+priority: high
+state_hub_task_id: "e84851b3-5f22-4a6f-83a1-76c4148839d9"
+```
+
+Write `the-custodian/docs/hub-ecosystem-architecture.md` capturing:
+
+- the three-layer model above;
+- entity ownership table (canonical owner per table family);
+- event-family mapping (`ProgressEvent` vs `InteractionEvent`);
+- capability catalog vs hub-capability-manifest relationship;
+- explicit non-goals (no repo merge, no State Hub retirement in this workplan).
+
+Update `hub-core/INTENT.md`, `hub-core/SCOPE.md`, `core-hub/INTENT.md`,
+`core-hub/SCOPE.md`, and `state-hub/SCOPE.md` with a short "Ecosystem
+position" section pointing to the decision doc.
+
+Done when all three repos reference the same layer diagram and ownership table.
+
+## Task: Normalize domain and naming metadata
+
+```task
+id: CUST-WP-0057-T02
+status: done
+priority: medium
+state_hub_task_id: "7d80dd25-7273-4cc9-aca8-77065f513c23"
+```
+
+Align repo identity metadata:
+
+- hub-core domain slug → `infotech` (library under FOS infra), with `inter_hub`
+  topic only where historical workplan IDs require it;
+- add a naming glossary (`hub-core` = library, `core-hub` = production framework,
+  `state-hub` = dev coordination) to each repo README;
+- update `.repo-classification.yaml` notes in hub-core and core-hub to reference
+  `CUST-WP-0057` and list sibling repos in `relations`.
+
+Done when agent instructions in all three repos use the glossary consistently.
+
+## Task: Wire reuse-surface capability relations
+
+```task
+id: CUST-WP-0057-T03
+status: done
+priority: medium
+state_hub_task_id: "868ba93c-8e69-48e9-8626-98a39b0688e8"
+```
+
+Update capability registry entries:
+
+- `capability.infotech.hub-core-library` → `supports` state-hub, `related_to` core-hub;
+- `capability.infotech.core-hub` → `depends_on` hub-core-library (utils/contracts),
+  `related_to` state-hub workstream-coordinate;
+- add `state-hub` capability entry if missing, with `depends_on` hub-core-library.
+
+Sync `registry/indexes/capabilities.yaml` in each repo and run reuse-surface
+federation publish when the operator lane is available.
+
+Done when `warden route find "hub ecosystem"` or reuse-surface search surfaces
+the three-repo stack as an intentional composition.
+
+## Task: Seed core-hub adoption workplan
+
+```task
+id: CUST-WP-0057-T04
+status: done
+priority: high
+state_hub_task_id: "c8638725-85e9-4bf7-9ba0-245859df299d"
+```
+
+Create `core-hub/workplans/CORE-WP-0009-hub-core-adoption-and-integration.md`
+with tasks for:
+
+1. Add editable `hub-core` dependency to `pyproject.toml`.
+2. Replace local `slugify()` with `hub_core.utils.slugs`.
+3. Evaluate `hub_core.utils.pagination` for `/api/v2` list endpoints.
+4. Document metadata isolation (separate SQLAlchemy bases) in core-hub architecture spec.
+5. Add contract test proving core-hub + hub-core versions pin together in CI.
+
+Done when CORE-WP-0009 exists with `status: ready` and T01–T02 scoped.
+
+## Task: Seed state-hub boundary workplan
+
+```task
+id: CUST-WP-0057-T05
+status: done
+priority: high
+state_hub_task_id: "a37b8c2b-7a97-48a9-93f9-21e66c832317"
+```
+
+Create `state-hub/workplans/STATE-WP-0074-hub-ecosystem-boundary-alignment.md`
+with tasks for:
+
+1. Document which routes are dev-hub-only vs hub-core-factory (audit `api/main.py`).
+2. Define optional read APIs for core-hub to ingest progress/messages without
+   duplicating tables (or record deferral with rationale).
+3. Add cross-repo smoke: state-hub progress POST visible to core-hub operator
+   evidence contract (if HTTP bridge is chosen).
+4. Confirm State Hub does not grow `/api/v2` Inter-Hub surfaces (core-hub owns those).
+
+Done when STATE-WP-0074 exists with `status: ready`.
+
+## Task: Shared contract — progress and evidence mapping
+
+```task
+id: CUST-WP-0057-T06
+status: done
+priority: medium
+state_hub_task_id: "74a9c81d-867a-4ae9-83cc-5e7beda78fbf"
+```
+
+Add `the-custodian/docs/hub-ecosystem-event-mapping.md` defining:
+
+- when to emit `ProgressEvent` (state-hub / dev coordination);
+- when to emit `InteractionEvent` (core-hub / widget ops evidence);
+- correlation fields (`subject_refs`, widget_id, hub_slug, workplan_id);
+- activity-core sink expectations for each family.
+
+Add fixture examples under `core-hub/contracts/fixtures/` and
+`hub-core/tests/fixtures/` (or custodian docs only if fixtures are premature).
+
+Done when ops-hub and activity-core owners can trace an event from dev action →
+production evidence without ambiguous dual-writes.
+
+## Task: Shared contract — capability identity bridge
+
+```task
+id: CUST-WP-0057-T07
+status: done
+priority: medium
+state_hub_task_id: "69c7db28-5bc8-4f3c-a2ac-84d27133864c"
+```
+
+Document how reuse-surface capability IDs (`capability.<domain>.<name>`) map to:
+
+- State Hub `capability_catalog` rows;
+- Core Hub `hub_capability_manifests` bodies;
+- reuse-surface registry entries.
+
+Deliverable: `the-custodian/docs/hub-ecosystem-capability-bridge.md` plus a
+worked example using `capability.infotech.hub-core-library` and
+`capability.infotech.core-hub`.
+
+Done when manifest activation in core-hub can reference a reuse-surface ID
+without inventing a parallel naming scheme.
+
+## Task: hub-core library extensions (delegate HUB-WP-0003)
+
+```task
+id: CUST-WP-0057-T08
+status: done
+priority: high
+state_hub_task_id: "64847fc3-9d79-4f6c-8e32-2973f3ce1286"
+```
+
+Execute `hub-core/workplans/HUB-WP-0003-ecosystem-consolidation-library-lane.md`:
+
+- optional async-friendly base/timestamp re-export seam for core-hub evaluators;
+- `hub_core.utils` coverage for slug/pagination parity tests;
+- `SCOPE.md` "Boundaries with sibling repos" table includes core-hub with
+  explicit "framework-only" vs "library" split;
+- bump package version minor when first core-hub consumer merges.
+
+Done when HUB-WP-0003 reaches `finished` and core-hub CI imports at least one
+hub-core utility module.
+
+## Task: Cross-repo CI pin and regression gate
+
+```task
+id: CUST-WP-0057-T09
+status: done
+priority: high
+state_hub_task_id: "d9dad241-2f3d-4715-873c-7deeac308764"
+```
+
+Add a custodian-orchestrated smoke script (or documented Make target chain):
+
+```bash
+cd ~/hub-core && uv run pytest -q
+cd ~/state-hub && uv run pytest -q
+cd ~/core-hub && uv run pytest -q
+```
+
+Record expected test counts and enforce after each consolidation PR. Optionally
+add a Forgejo workflow matrix that checks out sibling repos as path dependencies.
+
+Done when a single documented command sequence is the merge gate for
+CUST-WP-0057 changes.
+
+## Task: Closeout — update extraction boundary and bootstrap status
+
+```task
+id: CUST-WP-0057-T10
+status: done
+priority: medium
+state_hub_task_id: "4817f404-02a6-4f09-9499-bfb39c7a40f7"
+```
+
+Update:
+
+- `the-custodian/docs/hub-core-extraction-boundary.md` — add "Ecosystem composition"
+  section referencing core-hub framework exclusives;
+- `the-custodian/docs/fos-hub-bootstrap-sequence-status.md` — add consolidation
+  lane status under CUST-WP-0057;
+- mark open questions in `core-hub/docs/specs/data-model.md` resolved or explicitly
+  deferred with ADR links.
+
+Done when a new agent orienting from custodian docs sees hub-core, state-hub,
+and core-hub as one stack, not competing alternatives.
+
+## Success criteria
+
+- hub-core, core-hub, and state-hub each have a clear one-paragraph ecosystem
+  position in INTENT/SCOPE.
+- core-hub depends on hub-core for at least shared utilities; no new duplicate
+  slug/pagination helpers without justification.
+- Canonical owners are documented for workplans, `/api/v2` framework entities,
+  and dev coordination tables.
+- Capability registry relations link the three repos.
+- Full pytest regression passes in all three repos after each consolidation slice.
+
+## Non-goals
+
+- Merging repos or renaming `hub-core` / `core-hub` (glossary only).
+- Moving State Hub workplan tables into core-hub.
+- Replacing core-hub `/api/v2` with state-hub routes.
+- Publishing hub-core to PyPI (editable/path dependency remains fine).
+- Absorbing core-hub operator console into hub-core.
--- a/workplans/archived/260710-CUST-WP-0058-business-platform-enablement.md
+++ b/workplans/archived/260710-CUST-WP-0058-business-platform-enablement.md
@ -4,7 +4,7 @@ type: workplan
 title: "Business platform enablement — decisions, service contract, client plane"
 domain: infotech
 repo: the-custodian
-status: active
+status: finished
 owner: codex
 topic_slug: custodian
 created: "2026-07-10"
@ -174,16 +174,18 @@ Evidence: `docs/evidence/vergabe-teilnahme-delivery-lane-20260710.json`.

 ```task
 id: CUST-WP-0058-T08
-status: wait
+status: done
 priority: low
 state_hub_task_id: "203f7afa-0162-4906-a4f2-c4789cd127bc"
 ```

-Verify all three DRs resolved (or explicitly deferred with revisit
-conditions), the service contract standard is merged in canon, and
-downstream workplan skeletons (client-hub, fin-hub billing, coulomb.social
-rebuild + bubble.io migration) are handed to their owning repos. Update
-SCOPE.md Current State; archive this plan.
+**Done 2026-07-10.** DR-1/2/3 resolved; service contract accepted in canon.
+Handoffs delivered: fin-hub FIN-WP-0002 (msg `9c8e8ed4…`), core-hub
+CLNT-WP-0001 (msg `17f8c11b…`), vergabe-teilnahme gaps (msg `f49d2651…`),
+ops-hub registration (msg `f0374952…`), railiance-apps backup HIGH
+(msg `a1957cce…`), NetKingdom NK-WP-0011 triggers (msg `0d238b6e…`).
+coulomb.social rebuild seeded in `docs/coulomb-social-rebuild-seed.md`
+(no owning repo yet — created at project registration). SCOPE.md updated.

 ## Sequencing