hub-core/workplans/HUB-WP-0007-workload-projection-transport.md

---
id: HUB-WP-0007
type: workplan
title: "Authoritative workload projection transport"
domain: infotech
repo: hub-core
status: finished
owner: codex
topic_slug: custodian
created: "2026-08-23"
updated: "2026-08-23"
parent_workplan: RMGR-WP-0010
related:
  - HUB-WP-0006
  - RMGR-WP-0010-T04
  - RMGR-CONTRACT-WORKLOAD-REFERENCE-0001
state_hub_workstream_id: "1f767e78-ab36-5e62-a23a-31af0f21a723"
---

# Authoritative workload projection transport

## Goal

Transport Repo Manager's authoritative workload index through hub-core's
rebuildable cross-repository projection port without transferring workload
semantics, exposing Repo Manager persistence, or inferring identities.

## Approve and pin the owner interface

```task
id: HUB-WP-0007-T01
status: done
priority: medium
state_hub_task_id: "99787c58-f0b2-5e67-9816-ff4ea0ad6057"
```

Disposition: **approved** on 2026-08-23 by operator instruction to implement.
The accepted owner interface is
`helixforge.workloads.projection-transport.v1` at Repo Manager revision
`890f3b05b596047a31605c544c56ed8a4f011868`; its authoritative workload
contract implementation is revision
`b36b68bc5747aaeea412079c737f9f7e9d4b7dfb`. Validation passed with one
owner-ready interface and no errors. Hub-core accepts the objective,
deliverables, constraints, acceptance criteria, and verification without
reconstructing Repo Manager work.

## Freeze the normalized transport contract

```task
id: HUB-WP-0007-T02
status: done
priority: medium
state_hub_task_id: "24279a94-a23c-5468-8623-ecddcafaef3a"
```

Package a strict versioned input/output contract for records keyed by exact
`rapp_id` plus `workload_identity.name`, optional deployable membership,
source repository, declaration path, source Git revision, and canonical UTC
observation time. Preserve Repo Manager diagnostics and reject unsupported
versions or inferred identity.

Completed 2026-08-23. Packaged `helixforge.workload-projection` 1.0.0 defines
strict Repo Manager input pages, normalized output and exact-resolution
schemas, a read-only OpenAPI fragment, authority/compatibility policy, and the
nine-declaration fixture. Canonical UTC is required at the schema boundary;
identity and path consistency are also checked semantically.

## Implement durable rebuildable ingestion

```task
id: HUB-WP-0007-T03
status: done
priority: medium
state_hub_task_id: "cb0eb118-a968-51d4-84fc-0a9bf959a501"
```

Extend the injected `port.repo` boundary with workload pages. Deterministically
replace the active generation in PostgreSQL, retain source/rebuild provenance
and a canonical content hash, and keep the previous generation on invalid or
unavailable input.

Completed 2026-08-23. `WorkloadProjectionService` consumes a separate injected
`port.repo` workload client, validates complete paged transfers, rejects error
diagnostics, duplicate identity/deployables, unsupported versions, noncanonical
paths, and stale/reused snapshots, then atomically replaces the generation.
Migration `0004_workload_projection` persists projection state and normalized
records without foreign keys or Repo Manager imports. Invalid input preserves
the prior generation as stale and readiness reports current/stale/unavailable.

## Expose exact read-only HTTP and MCP resolution

```task
id: HUB-WP-0007-T04
status: done
priority: medium
state_hub_task_id: "722dfd4a-62d3-59b0-9494-08ec8f184571"
```

Expose list and exact-reference queries through `port.projection.query` and
matching MCP tools. Exact resolution returns `resolved` or `unknown` without
repository-name, owner, alias, or path inference. No workload mutation route is
permitted.

Completed 2026-08-23. GET-only list and exact-resolution routes expose
normalized records with content/source provenance. Filters and cursors use
only explicit `rapp_id`, name, and deployable values. Resolution returns
`unknown/not_found` or `unknown/deployable_not_declared`; it never consults
owner, repository, path, or alias fallbacks. MCP tools `query_workloads` and
`resolve_workload_reference` call the same HTTP surface.

## Prove conformance and hand off

```task
id: HUB-WP-0007-T05
status: done
priority: medium
state_hub_task_id: "04569701-6cb4-5762-ac9b-a9dec4e2bb52"
```

Ingest a nine-declaration Repo Manager fixture; prove deletion plus full rebuild
equivalence, unknown-reference behavior, canonical UTC timestamps, durable
reopen, provenance, deterministic hashes/order, read-only OpenAPI, and absence
of Repo Manager private-model or foreign-database coupling. Run `make test` and
`make conformance`, then reply with owner identifiers and evidence.

Completed 2026-08-23. Tests ingest and query all nine fixture declarations,
prove exact/unknown resolution, deletion plus equivalent full rebuild,
generation-bound cursors, UTC rejection, outage/stale behavior, durable reopen,
schema-valid HTTP responses, GET-only OpenAPI, and absence of private-model or
foreign-database coupling. `make test` passes 100 tests, live
`make conformance` passes 8/8, the wheel builds, and PostgreSQL migrations
render through `0004_workload_projection` (501 lines).

## Acceptance

- [x] Owner interface disposition and source revisions recorded
- [x] Normalized transport contract is versioned and packaged
- [x] Durable projection rebuild preserves authority and provenance
- [x] HTTP/MCP exact reference queries never infer identity
- [x] Nine-declaration and rebuild conformance evidence passes