tegwick
9724b273a1
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a053ff-1d6f-7fe2-ac1c-a6eb40a42a0c
198 lines
8.3 KiB
Markdown
198 lines
8.3 KiB
Markdown
---
|
|
id: HUB-WP-0006
|
|
type: workplan
|
|
title: "Repository classification aggregation and navigation"
|
|
domain: infotech
|
|
repo: hub-core
|
|
status: active
|
|
owner: codex
|
|
topic_slug: custodian
|
|
created: "2026-08-22"
|
|
updated: "2026-08-22"
|
|
parent_project: prj-state-hub-retirement
|
|
parent_workplan: STATE-WP-0079
|
|
related:
|
|
- HUB-WP-0004
|
|
- HUB-WP-0005
|
|
- RMGR-WP-0008
|
|
- RMGR-CONTRACT-CLASSIFICATION-0001
|
|
state_hub_workstream_id: "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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
id: HUB-WP-0006-T06
|
|
status: wait
|
|
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.
|
|
|
|
## Acceptance
|
|
|
|
- [x] Repo Manager v1.0 authority and projection contract accepted
|
|
- [x] Hub-side projection and compatibility alias contract versioned
|
|
- [x] Rebuildable durable ingestion passes provenance and failure checks
|
|
- [x] HTTP/MCP navigation reads only the derived projection
|
|
- [ ] A5/A4 consumer comparison and rollback evidence recorded
|