state-hub/docs/a5-topic-spine-comparison-packet.md

A5 topic-spine comparison packet (draft)

Task: STATE-WP-0098-T01 (A5) and STATE-WP-0098-T02 (A4 section) Receiver: hub-core HUB-WP-0006-T06 Captured: 2026-10-13, read-only GETs against State Hub primary/railiance01 Cases: docs/evidence/a5-topic-spine-comparison-cases.json (10 cases) Status: draft. Not yet sent to hub-core. No route, flag or deployment was changed.

1. Where the A5 and A4 item lists come from

The counts "A4 / 22" and "A5 / 8" in docs/retirement-cutover-slice-plan.md come from the original slice plan (commit 613477b). That plan grouped inventory items by capability: A5 is topic-spine (8); A4 is work-coordination-ui (14) plus repo-ui (8). The item list is prj-state-hub-retirement/inventory/state-hub-disposition.yaml (SHR-INV-0001). Items were matched on their capability field; none of them were guessed.

Correction to the framing. The 8 A5 items are not 8 read endpoints:

Inventory id	Kind	Read?
route:GET:/topics/	REST	read
route:GET:/topics/{topic_id}	REST	read
mcp:get_topic	MCP tool (wraps the two GETs plus /progress)	read
route:POST:/topics/	REST	write
route:PATCH:/topics/{topic_id}	REST	write
route:DELETE:/topics/{topic_id}	REST	write
mcp:create_topic	MCP tool	write
table:topics	dataset	data

That leaves three read surfaces to compare. One more read surface is not in the inventory: the MCP resource state://topics. The three writes are out of scope for a read switch. They should be retired or frozen, not redirected, because the receiver accepts no classification writes. Classification fields on /repos/ (domain_slug, category, tags, stake, mechanics, topic_id) belong to A1 in the inventory. They are still the real counterpart of the hub-core projection, so A5-C05 to A5-C07 compare them.

2. Callers

Legacy meter. None of the topic routes is metered. GET /legacy-meter/interfaces returns 16 interfaces, all for workstreams, SBOM or messages. The weekly reviews up to legacy-meter-weekly-review-20261013.json do not mention topics. State Hub has no other per-route usage telemetry. So there are no volume or last-seen figures. To get them, register rest_api:GET /topics/ and rest_api:GET /topics/{topic_id} in the meter before the switch window. That is a State Hub write and needs approval.

Code callers (ripgrep over /home/worsch/*, excluding archives and workplans). Every direct caller is inside state-hub:

Caller	Route	Use
custodian_cli.py (statehub) l.178, 481	GET /topics/?status=active (+ POST l.184)	resolve topic for register/brief
statehub_register.py l.851, 900	GET /topics/?status=active, POST /topics/	repo registration
scripts/consistency_check.py l.3398, 3784, 3969	GET /topics/{id}, GET /topics	fix-consistency (C-06 etc.)
scripts/promote_intake.py, validate_repo_adr.py, normalize_attached_repo_workplans.py, update_agent_instruction_files.py, register_project.sh	GET /topics[/?status=active]	slug/id/domain lookup
mcp_server/server.py (state://topics, get_topic, l.208, 263, 2402, 2757)	GET /topics, GET /topics/{id}	MCP clients (agents)
Dashboard: tasks, decisions, dependencies, extensions, interventions, techdept, todo, workstreams pages	GET /topics/	topic label lookup

The only hit outside state-hub is kontextual-engine/core/cmis.py. It builds a CMIS path, not a State Hub call, so it is not a caller.

Indirect alias consumers. 126 repos carry a topic_id in AGENTS.md or .claude/rules/repo-identity.md. They use it in /workplans/?topic_id= (A2) and in progress events (B3). They never call /topics/, but they need the topic UUIDs to stay stable until those slices drop topic_id.

3. Legacy response shapes (captured live)

• GET /topics/?status=active → 200, a list of 16 rows. Each row has {id: uuid, slug, title, description, domain_slug, status, created_at, updated_at}. All 16 are active. Headers: Cache-Control: max-age=60, ETag.
• GET /topics/{id} → 200, the same fields plus workstreams: [WorkstreamStub]. An unknown id → 404. Defect: workstreams is always []. The model relation was renamed workplans, but the schema still reads workstreams. No consumer can depend on its content.
• MCP get_topic(slug) → {topic: <GET /topics/{id}>, recent_progress: [<progress>]}.
• Repo classification (GET /repos/, 154 rows: 149 active, 5 archived) includes id, slug, canonical_slug, domain_slug, secondary_domains, category, capability_tags, business_stake, business_mechanics, topic_id, classified_at, classified_by. 58 repos have a topic_id and 96 do not; 23 have no category.
• The topic ids and slugs are listed in the JSON case file (A5-C01/C02 use all 16).

4. Hub-core side and alias expectations

• Routes (hub_core/runtime/repository_navigation_routes.py, GET only): GET /ports/projections/repository-navigation/repositories (filters primary_domain, secondary_domain, category, capability_tag, business_stake, business_mechanic; cursor; limit ≤ 500) and GET /ports/projections/repository-navigation/facets/{kind}/{value}. MCP: query_repository_navigation, get_repository_navigation_facet. 503 means no accepted projection; 409 means a stale cursor.

• Contract: helixforge.repository-navigation 1.0.0 (hub_core/contracts/repository_navigation/v1_0_0/, docs/repository-navigation-contract.md). The output carries repositories[] keyed by registrar repository_id, facets[], legacy_topic_aliases[], provenance and content_hash.

• Identity. Join on legacy repo id == repository_id. Repo Manager's registry import takes the UUID from State Hub /repos/{slug} (repo_manager/repository_publisher.py). That this holds for all 123 rows in the deployed registry is unverified. Slugs are labels, not identity.

• Topic aliases. Each alias maps one State Hub topic UUID/slug to exactly one facet and must carry expires_at and a residual_owner. The expected mapping is facet_kind = primary_domain and facet_value = topic.domain_slug, with residual owner STATE-WP-0079. This mapping is lossy:

  • several topics share a domain (7 topics are infotech);
  • 4 repos sit under a topic of a different domain (adaptive-pricing, commerce-canon, informed-decision, whynot-design);
  • 96 repos have no topic.

  A topic is a grouping label, not a facet, so exact topic membership has no hub-core counterpart (A5-C04).

• Legacy fields with no counterpart: topic title, description, status, created_at, updated_at, workstreams; in get_topic, recent_progress (B3) and workplans (A2); in repos, classified_at and classified_by (provenance replaces them).

5. Comparison cases

Ten cases are defined in the JSON file:

Id	What it compares	Expected result
C01/C02	Topic list and topic-by-id against the aliases	equal once aliases exist
C03	Unknown topic	404 vs empty facet, a documented difference
C04	Topic membership vs domain facet	subset, a documented difference
C05	Full per-repo classification parity on the id join	equal; cardinality gap 154 vs 123 to be listed
C06	state-hub spot check	equal
C07	Domain facet counts	equal
C08	MCP get_topic	partial
C09	Fields with no counterpart	none to compare
C10	Rollback read	equal to the 2026-10-13 capture

6. Fallback and rollback

The fallback is the current State Hub read routes, which stay unchanged throughout: GET /topics/, GET /topics/{topic_id}, and MCP get_topic/state://topics. Rollback means setting RM_SLICE_TOPICSPINE back to off and confirming with A5-C10.

Caveat: RM_SLICE_TOPICSPINE does not exist in any code in State Hub, hub-core, rapp-core-hub or repo-manager. The slice plan calls the RM_SLICE_* names "proposed controls, not proof of deployed flags". So today the rollback is "callers keep or restore the legacy base URL". Someone must implement the flag, or name a per-caller switch instead, before the switch window.

7. Gaps blocking hub-core from running the comparison

1. No alias source. The hub-core runtime always emits legacy_topic_aliases: [] (repository_navigation.py l.74). The only alias in the fixtures expired on 2026-09-30. C01, C02 and C08 cannot pass until someone owns alias seeding: hub-core config, or a State Hub export of the 16 topics.
2. No flag. RM_SLICE_TOPICSPINE is not implemented (see §6).
3. No usage figures. The topic routes are unmetered, so there is no volume or last-seen data.
4. Candidate access not verified. The base URL and auth for the candidate routes have not been checked from State Hub. The only source is the 2026-10-03 receipt (Helm rev 31, 123/123 accepted). Nobody has made a live candidate GET this session.
5. Cardinality gap. 154 legacy repos vs 123 published. The 31-row difference needs an explanation before C05 can be judged.
6. The real switch targets are State Hub's own tools. All direct callers are State Hub tools (CLI, consistency check, MCP, dashboard). They use topics for id/slug/domain lookup and for writes. A read switch to navigation facets only covers the domain lookup.

A4 work/repo UI callers

The 22 A4 items are Observable dashboard views in state-hub/dashboard, not API endpoints. They are served by make dashboard on the workstation (:3000) and viewed by the operator (Bernd). The inventory lists repo-manager as their owner, but RMGR-ADR-003 excludes a Repo Manager dashboard. The slice plan names "hub-core projection + UI clients" as the receiver. No hub-core page equivalents were checked (unverified). The backing reads below come from each page's apiFetch/fetch/FileAttachment calls.

View	Backing reads	Proposed owner to ask
/tasks, /tasks/*, /todo, /interventions, /workstreams, /workstreams/*, /dependencies	/tasks/, /workplans/, /workplans/index, /state/deps, /repos/, /topics/, /contributions/, /technical-debt/	hub-core (work-record projection, A2) with repo-manager (file authority)
/decisions	/decisions/, /topics/	hub-core; external link from railiance-platform (docs/credential-change-approval.md, CCR yaml decision_dashboard_url)
/goals	/domain-goals/, /repo-goals/, /domains/, /repos/	hub-core / repo-manager (unverified owner)
/wsjf-triage	/progress/, /workplans/index	hub-core (B3 progress)
/workplan-queue	/execution/*	activity-core (C1)
/repos, /repos/*, /repo-sync, /contributions, /extensions, /techdept	/repos/, /domains/, /extension-points/, /technical-debt/, /contributions/, /workplans/, build-time data/repos.json, gitea-inventory.json	repo-manager (A1 registry) via hub-core navigation
/sbom	/sbom/* (Nexus-backed)	sbom-nexus (rapp-sbom-nexus); archived railiance-cluster/bootstrap docs link it
/policy/intake-doc, /policy/workstream-dod, /policy/repo-doi	static policy text	policy-nexus (B4)
/suggestions	page already removed (E1)	none; already retired

That makes 21 live views plus /suggestions, which is already gone. Pending approval, ask each owner for two things:

• A candidate read smoke. The owner's endpoint returns the same rows for the backing reads above, compared on ids and counts.
• A reversible switch plan. The page reads the candidate behind a toggle. Rollback re-points the page, or removes the redirect, to the retained State Hub UI, which stays unchanged.

railiance-platform should also be asked where decision_dashboard_url should point after cutover. No messages have been sent.