hub-core/workplans/HUB-WP-0006-repository-classification-navigation.md

id	type	title	domain	repo	status	flavor	owner	topic_slug	created	updated	parent_project	parent_workplan	related	state_hub_workstream_id
HUB-WP-0006	workplan	Repository classification aggregation and navigation	infotech	hub-core	blocked	implementation	codex	custodian	2026-08-22	2026-10-13	prj-state-hub-retirement	STATE-WP-0079	HUB-WP-0004 HUB-WP-0005 RMGR-WP-0008 RMGR-CONTRACT-CLASSIFICATION-0001	05ebd06e-4af8-5f6c-918c-c143c1520e00

Repository classification aggregation and navigation

Goal

Consume Repo Manager's validated repository-classification projections and provide rebuildable cross-domain aggregation/navigation without creating a second classification authority. Supply the hub-core receiving surface needed for State Hub retirement slices A5 and the repository-facing part of A4/B5.

Accept the classification projection boundary

id: HUB-WP-0006-T01
status: done
priority: high
state_hub_task_id: "2a45aa34-ffa1-5432-9bfd-a6725708d807"

Review RMGR-CONTRACT-CLASSIFICATION-0001 version 1.0 and record the hub-core authority, validation, versioning, provenance, failure, and A5 routing boundary.

Completed 2026-08-22. docs/adr/ADR-0002-repository-classification-projections.md accepts the contract without a schema gap. Repository files remain authority; Repo Manager validates and publishes; hub-core derives navigation only; and STATE-WP-0079 retains the consumer-route switch and rollback flag. State Hub decision 7168ee97-71bd-43e8-9d8b-0d5532743d08 records the same single-authority boundary.

Freeze the hub-side projection contract

id: HUB-WP-0006-T02
status: done
priority: high
state_hub_task_id: "fa5c37c5-40cb-5ddf-bb01-72b00a8c8931"

Define the input envelope, supported contract versions, stable repository identity, cursor/snapshot semantics, provenance, diagnostics, and the derived domain/category/tag/stake/mechanic views. Define legacy topic aliases as temporary compatibility metadata, not mutable topic authority.

Completed 2026-08-22. Packaged helixforge.repository-navigation 1.0.0 defines the strict Repo Manager page envelope, stable registrar UUID identity, atomic snapshot/rebuild and cursor rules, per-repository provenance, failure diagnostics, all six derived facet kinds, read-only query routes, and expiring State Hub topic aliases with residual ownership. Both representative fixtures validate, the wheel contains the versioned artifacts, and the full suite passes 72 tests.

Implement Repo Manager ingestion and rebuild

id: HUB-WP-0006-T03
status: done
priority: high
state_hub_task_id: "8b79be6d-d1aa-5134-b2f7-3dc088a7b3fd"

Add an injected port.repo client, deterministic full rebuild plus incremental upsert/delete behavior, durable PostgreSQL projection tables, content hashes, and dependency-aware readiness. Reject invalid or unsupported projection versions without coercion.

Completed 2026-08-22. RepositoryNavigationService consumes an injected port.repo client, validates the exact v1.0.0 envelope plus cross-page semantics, and applies deterministic full or incremental generations with idempotent duplicate handling. Migration 0003_repository_navigation persists active state, normalized repository rows, and all derived facets in one atomic transaction. Invalid versions and transfers preserve the last generation as stale; readiness distinguishes current, stale, unavailable, and disabled dependencies. PostgreSQL migration SQL renders through head and the 77-test suite covers durable reopen, startup injection, outage, rejection, full rebuild, upsert, and deletion.

Expose projection query and MCP navigation

id: HUB-WP-0006-T04
status: done
priority: high
state_hub_task_id: "59cbe5b8-ab7e-5274-b4d2-a38246df89e3"

Expose cross-repository query routes and MCP tools for domain, secondary domain, category, capability tag, business stake, and business mechanic. Responses carry source revision and rebuild provenance. No endpoint writes classification authority.

Completed 2026-08-22. The read-only projection port now supports cross-facet HTTP queries plus direct facet resolution for primary/secondary domain, category, capability tag, business stake, and business mechanic. Filters OR within a family and AND across families; snapshot/filter-bound cursors reject reuse after rebuild with 409. Responses validate against the frozen output schema and carry source revision, observed provenance, rebuild time, status, and content hash. MCP tools query_repository_navigation and get_repository_navigation_facet expose the same navigation fields. Runtime OpenAPI inspection confirms that every navigation operation is GET-only.

Prove conformance and failure behavior

id: HUB-WP-0006-T05
status: done
priority: medium
state_hub_task_id: "901f0f0c-270c-5939-8c98-fcae6988e8f3"

Add contract fixtures and checks for full rebuild, incremental changes, deletion, duplicate delivery, unsupported versions, Repo Manager outage, stable ordering/cursors, provenance, and absence of classification writes or foreign database access.

Completed 2026-08-22. A packaged incremental fixture and 15 focused ingestion checks now cover single- and multi-page full rebuild, incremental upsert plus delete, duplicate delivery, snapshot-ID reuse with changed content, unsupported versions, upstream outage, inconsistent-page atomicity, durable reopen, stable ordering, filter- and generation-bound cursors, response provenance, GET-only HTTP navigation, and projection tables without foreign database keys. The wheel rebuild succeeds and the complete suite passes 88 tests.

Hand A5/A4 navigation to State Hub retirement

id: HUB-WP-0006-T06
status: wait
depends_on: [STATE-WP-0079-T04]
blocking_reason: "Publisher admission is complete; State Hub and selected A5/A4 consumer owners must supply parity cases, caller/alias mapping, a bounded switch window and rollback/traffic receipts."
priority: high
state_hub_task_id: "7c8225f7-03dc-57b0-a668-c3d781bd828a"

With STATE-WP-0079, compare legacy topic/navigation consumers with the new projection, retain explicit aliases where required, run owned consumer smokes, switch A5 through RM_SLICE_TOPICSPINE, and record rollback plus residual expiry. Wait on T02-T05 and the State Hub cutover window.

Readiness checkpoint 2026-08-22: T02-T05 are complete, but T06 remains wait. RMGR-WP-0008-T06 delivered validation and the authority contract, not a transport that emits the frozen paged envelope with registrar repository_id values. A Repo Manager-owned port.repo publisher/adapter is therefore still required before comparison can start. Hub-core commits a701dc8 through 93a9151 also require migration/image deployment, and STATE-WP-0079-T04 remains progress. Do not move RM_SLICE_TOPICSPINE from off until those three gates close; rollback remains the flag set to off plus the prior State Hub read route.

Publisher checkpoint 2026-09-01: Repo Manager revision 10d87e21f50a0205b62688604c78c6f43a7171e5 now emits the exact frozen envelope through a read-only, bearer-capable HTTP port.repo route with stable registrar UUIDs and HMAC-bound paging. Hub-core's built-in HTTP client refreshes at startup and on a configured interval. Live conformance accepted 123 repositories over five pages as one current generation; Repo Manager evidence: docs/evidence/RMGR-WP-0013-live-conformance-2026-09-01.md.

Deployment checkpoint 2026-09-01: Helm revision 24 runs the Forgejo-backed publisher and hub-core image dda93db privately on railiance01. Live verification accepts 114 public repositories in a 3.45-second full scan and reports nine private sources as bounded errors. T06 remains wait only on RAPPCOREHUB-WP-0003-T04: a dedicated read:repository Forgejo identity and an error-free 123-repository admission proof. No host checkout or State Hub runtime dependency remains.

T06 still waits only on production placement/networking and deployment of the two committed runtimes. The public Core Hub cluster does not own the host-local Repo Manager checkout registry; do not solve that by mounting a broad home directory or restoring State Hub as the classification authority. Once a scoped publisher endpoint is deployed and the candidate migration/image is rolled out, comparison and RM_SLICE_TOPICSPINE can proceed.

Loose-ends review 2026-09-27: T01-T05 remain the only work owned by this repo, and all five are done. T06 has no remaining hub-core code path — it is waiting on RAPPCOREHUB-WP-0003-T04 (a dedicated read:repository Forgejo identity plus an error-free 123-repository admission proof) and production placement/networking outside this repository. Marking the workplan blocked rather than active since nothing further can move here until that external gate closes.

A5 packet intake 2026-10-13: State Hub delivered the comparison packet (state-hub/docs/a5-topic-spine-comparison-packet.md, cases docs/evidence/a5-topic-spine-comparison-cases.json, A5-C01..C10). It named two hub-core gaps: no alias source, and no RM_SLICE_TOPICSPINE. T07 closes both in code. The flag stays off everywhere, so T06 remains wait for the deployed candidate run and the switch window.

Seed legacy topic aliases and implement the A5 rollback switch

id: HUB-WP-0006-T07
status: done
priority: high
depends_on: []

Done 2026-10-13 (commit 9e4d5ba). Not pushed or deployed. The flag has not been changed in any environment.

• Alias source: hub_core/runtime/data/legacy_topic_aliases.json, alias set 2026-10-13.1. It holds the 16 active topics from State Hub's 2026-10-13 GET /topics/?status=active capture. Each maps to primary_domain = domain_slug, with residual_owner STATE-WP-0079 and expires_at 2027-03-31T23:59:59Z. The expiry is a conservative choice: it covers the switch window plus a dual run, and it can be renewed by editing the seed and bumping its version. The seed is validated against the 1.0.0 legacyTopicAlias schema and is never fetched live. Topic UUIDs are kept verbatim. Three slugs with underscores (inter_hub, vergabe_teilnahme, citation_evidence_mvp) are emitted with hyphens, because the 1.0.0 pattern forbids _. Emitting the exact spelling needs a contract patch.

• Flag: RM_SLICE_TOPICSPINE takes off, shadow or on; the default is off.

  • off leaves the output byte-for-byte unchanged (legacy_topic_aliases: []).
  • shadow serves the aliases for comparison only.
  • on declares hub-core the switched A5 read source.

  Rollback is setting the flag back to off. The values are documented in docs/runtime.md.

• Local comparison against fixtures: see tests/test_legacy_topic_aliases.py.

  • Pass: A5-C01 (16/16 aliases equal after the _→- normalisation), A5-C02 and the identity part of A5-C08 (each topic id resolves to exactly one alias), and the hub-core half of A5-C10 (off withdraws the aliases).
  • A5-C03 differs from the packet's expectation. An unknown domain returns 400, because the runtime validates the controlled vocabulary; it does not return 200 with an empty list. A known domain with no repositories returns 200 [].
  • A5-C04, C05, C06 and C07 need the deployed registry. The fixtures hold only two synthetic repositories.
  • A5-C09 has nothing to compare.
  • The State Hub half of C10 is a legacy read.

• Tests: full suite: 488 passed, 3 skipped.

• Still needed before T06 can run live:

  • deploy an image containing 9e4d5ba and set shadow on the candidate only, after approval;
  • a verified candidate base URL and auth;
  • the 154 vs 123 repository gap (out of scope here and unexplained);
  • topic-route usage figures from the legacy meter;
  • caller-owner switch plans.

Acceptance

• Repo Manager v1.0 authority and projection contract accepted
• Hub-side projection and compatibility alias contract versioned
• Rebuildable durable ingestion passes provenance and failure checks
• HTTP/MCP navigation reads only the derived projection
• A5/A4 consumer comparison and rollback evidence recorded

Dependency review — 2026-10-04

RAPPCOREHUB-WP-0003-T04/T05 are done. The owner's retained receipt rapp-core-hub/docs/evidence/2026-10-03-private-publisher-admission.json records Helm revision 31, 123/123 publisher acceptance with zero errors and repo_manager_projection: ok; rollback revision 30. This supersedes the older credential, registry correction, placement and candidate-admission blockers above. These are reviewed owner receipts, not a new live probe this session.

The remaining T06 gate is STATE-WP-0079-T04's A5/A4 consumer cutover, as confirmed by state-hub/docs/retirement-cutover-slice-plan.md. State Hub must enumerate the actual callers/legacy responses, alias expectations and comparison cases; selected UI/client owners must provide a candidate read smoke and reversible switch plan. State Hub retains authority for the cutover window, old-route fallback and metered acceptance. Resume T06 when that comparison packet exists; use the deployed projection to run it and attach parity/rollback receipts. Do not count publisher readiness as a caller switch. All local implementation tasks remain done and this workplan remains blocked on the external acceptance packet.