repo-manager/workplans/RMGR-WP-0013-repository-classification-publisher.md

---
id: RMGR-WP-0013
type: workplan
title: "Repository classification projection publisher"
domain: infotech
repo: repo-manager
status: finished
owner: codex
topic_slug: infotech
created: "2026-09-01"
updated: "2026-09-01"
parent_project: prj-state-hub-retirement
parent_workplan: STATE-WP-0079
related:
  - HUB-WP-0006
  - RMGR-WP-0008
state_hub_workstream_id: "b0da503c-755d-5075-a71e-71d9b5c1f767"
---

# Repository classification projection publisher

## Goal

Publish Repo Manager's validated fleet classification view through the frozen
`helixforge.repository-classification-projection` 1.0.0 `port.repo` contract,
including registrar UUIDs, atomic snapshot provenance, and safe paging, so
hub-core can rebuild repository navigation without reading State Hub tables.

## Freeze the publisher mapping

```task
id: RMGR-WP-0013-T01
status: done
priority: high
state_hub_task_id: "347d8ac8-2a69-57e3-ae6c-a75dd2b96234"
```

Map repository registry identity, lifecycle, checkout observation, classification
authority, revision provenance, diagnostics, and the exact hub-core envelope.
Keep host paths and credentials outside the published contract.

**Result (2026-09-01):** the mapping pins registrar UUID, canonical slug,
lifecycle, validated file classification, Git HEAD, classification-file SHA-256,
and canonical UTC observation time. The closed envelope excludes local paths,
remotes, work records, source bodies, and credentials.

## Implement registry-backed snapshot publication

```task
id: RMGR-WP-0013-T02
status: done
priority: high
state_hub_task_id: "d113429c-2015-515e-b1aa-9d5d339219dd"
```

Build deterministic full snapshots from an operator-owned local repository
registry, validate every classification at observation time, and publish stable
registrar UUID identities with source fingerprints and Git revisions.

**Result (2026-09-01):** `repository_publisher.py` loads a strict private
operator registry, rejects duplicate identity and unsupported lifecycle, and
builds full UUID-ordered snapshots. The primary-State-Hub bootstrap uses
bounded direct identity reads with retries and never trusts remote host paths.

## Implement the HTTP port and paging integrity

```task
id: RMGR-WP-0013-T03
status: done
priority: high
state_hub_task_id: "f5dde253-bbdb-5624-b7dd-399609861bcf"
```

Expose a read-only FastAPI `port.repo` route. Bind opaque cursors to the exact
snapshot and page size with an HMAC, retain bounded in-flight snapshots, and
fail closed on expired, malformed, or mismatched cursors.

**Result (2026-09-01):** the read-only FastAPI runtime exposes health,
readiness, and `GET /ports/repositories/classifications`. Cursors are
HMAC-SHA256-bound to snapshot, offset, and page size; in-flight snapshots are
bounded; optional bearer authentication is constant-time checked.

## Prove cross-repository conformance

```task
id: RMGR-WP-0013-T04
status: done
priority: high
state_hub_task_id: "48d13bee-4f5f-5787-93a5-321466192afc"
```

Exercise single- and multi-page transfers through hub-core's frozen consumer,
including stable ordering, provenance, malformed registry state, invalid
classification, cursor tampering, and preservation of the last good generation.

**Result (2026-09-01):** unit and cross-repository tests pass. A live five-page
transfer carried all 123 registered classified checkouts into hub-core and was
accepted as one current generation. Evidence:
`docs/evidence/RMGR-WP-0013-live-conformance-2026-09-01.md`.

## Package and hand off deployment

```task
id: RMGR-WP-0013-T05
status: done
priority: medium
state_hub_task_id: "9dbdbcfc-f485-50fb-92b1-3e084563d276"
```

Package the publisher runtime, document registry bootstrap and refresh, record
evidence, and hand the concrete endpoint/configuration to HUB-WP-0006-T06.

**Update (2026-09-01):** placement is resolved to the `railiance01` Core Hub
cluster. Helm revision 24 now runs the digest-pinned publisher from a committed
stable UUID-to-Forgejo registry and reads each classification at the exact
default-branch commit through the private in-cluster Forgejo Service. Live
verification completes the full scan in 3.45 seconds, accepts 114 public
repositories, and reports the nine private `rapp-*` repositories as bounded
errors. Final admission is handed to `RAPPCOREHUB-WP-0003-T04`, which waits for
a dedicated `read:repository` Forgejo identity; reusing the operator/admin PAT
or another workload's token is explicitly disallowed.

## Acceptance

- [x] Every published repository is keyed by its registrar UUID
- [x] The output validates as contract 1.0.0 without hub-core coercion
- [x] Pages cannot be mixed across snapshots or page sizes
- [x] Invalid source state cannot replace hub-core's last accepted generation
- [x] Runtime and deployment handoff are documented and reproducible