state-hub/workplans/STATE-WP-0084-forge-read-for-private-repositories.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	related	state_hub_workstream_id
STATE-WP-0084	workplan	Derive private repositories, and report unreadable as unreadable	infotech	state-hub	active	codex	infotech	2026-08-26	2026-08-26	CUST-ADR-012 STATE-WP-0083 MASON-WP-0003	9c4b8c79-edba-5d2d-ad37-a45707e89304

Derive private repositories, and report unreadable as unreadable

Goal

Consume the forge read credential that ops-mason/MASON-WP-0003 builds, so derivation covers private repositories — and make a repository central cannot read report as unreadable rather than as an error or, worse, as a repository whose records no longer derive.

Why this exists

STATE-WP-0083-T04 reset 121 repositories on 2026-08-26. Nine failed identically:

fatal: could not read Username for 'https://forgejo.coulomb.social'

rapp-core-hub, rapp-issue-core, rapp-openbao, rapp-policy-nexus and five others are invisible to derivation entirely. ADR-012's premise — the forge is the projection source — holds only for repositories central can read, and nothing in the current design says so.

Split from MASON-WP-0003

The credential lane itself (OpenBao policy, AppRole, KV path, and the warden route find catalog entry) is ops-mason's to build: that repository exists to build "AppRoles, policies, and KV secret paths so ops-warden always has something real to route to". Deployment plumbing and derivation code are this repository's.

T01 does not depend on the credential and should land first. T02 and T03 wait on MASON-WP-0003-T02.

Distinguish "cannot read" from "does not exist"

id: STATE-WP-0084-T01
status: done
priority: high
state_hub_task_id: "e955067d-2152-59f7-b672-12755ceb26b0"

A repository the hub is not permitted to read must be reported as unreadable — a named condition — not as a generic clone error and never as an empty derivation.

Today the reset treats a failed clone as an error, which is correct only by accident: if a clone ever returned empty instead of failing, every record in that repository would be proposed for retirement. That is the failure that nearly retired vergabe-teilnahme, and it must be impossible here by construction rather than by luck.

An empty clone result and an unreadable repository must both be incapable of producing retirement work. Retirement proposals require a successful read that positively lacks the record.

This also carries the decision in MASON-WP-0003-T01: a per-repository grant is only safe to choose if a missing grant surfaces as a named condition. Until this lands, the narrow option fails silently.

Acceptance: an unreadable repository is reported as unreadable; a clone that succeeds but returns nothing produces no retirement proposals; both cases are covered by tests that fail if the retirement path is reachable from either.

Done 2026-08-26. api/services/forge_projection.py:

• ForgeUnreadableError subclasses ForgeDeriveError, so existing callers keep catching it while new ones can tell the cases apart. A permission-shaped git failure is classified into it; a genuine fault stays a plain error. Forgejo's 404 for an unauthenticated private repository classifies as unreadable, because the two are indistinguishable at this layer and the safe reading of an ambiguous answer is the one that cannot destroy a record.
• _run_git runs with GIT_TERMINAL_PROMPT=0. Without it an unattended pass blocks on a username prompt instead of failing, and an unreadable repository is only observable if it fails.
• DerivedProjection.records_source_present / .retirement_eligible separate "no records found" from "no records exist". A checkout with no workplans/ directory can no longer evidence an absence.
• diff_against_hub withholds stale rather than computing and filtering it, and says so in stale_withheld. would_remove is 0 for such a source.
• reset_repository_projection returns status="unreadable" for a repository it may not read, and refuses retirement from an ineligible source even when acknowledge_retirements=True — consenting to a conclusion is not the same as the evidence for it existing.
• reset_fleet_projection keeps unreadable repositories out of errors, in their own bucket with its own count. Nine repositories in an error bucket read as nine broken repositories; they were nine we were not allowed to read.

13 tests in TestUnreadableIsNotMissing (tests/test_forge_projection.py); 58 pass across the forge/projection/backfill suites.

Deliver the credential to the pod

id: STATE-WP-0084-T02
status: wait
priority: medium
state_hub_task_id: "d8d41a89-1ebc-5118-bb73-cf8d8c114e16"

Blocked on MASON-WP-0003-T02.

Make the credential available to the state-hub deployment as a Kubernetes Secret, mounted or injected, referenced by the chart the same way state-hub-env already is.

It must not be baked into the image and must not be committed to the chart. Rotation must not require a chart change or a redeploy.

Acceptance: the pod can read the credential; nothing in the repository contains it; rotating the token does not require a redeploy.

Teach the derivation to use it

id: STATE-WP-0084-T03
status: wait
priority: medium
state_hub_task_id: "b22b24d9-7ed3-533c-bda7-3130693cf4d2"

Blocked on T02.

derive_from_forge() clones anonymously. It should use the credential when present and continue working without it — a hub with no token must still derive public repositories rather than failing wholesale.

Credentials must never reach the clone URL in a way that lands in logs or process listings: use a credential helper or an HTTP header, not an embedded userinfo URL.

Acceptance: private repositories derive; a hub without the credential still derives public ones; no credential appears in logs, process listings, or recorded clone URLs.

Confirm the nine

id: STATE-WP-0084-T04
status: wait
priority: medium
state_hub_task_id: "33c09a78-5974-57c6-bb7f-ad73082046bb"

Blocked on T03.

Re-run the fleet reset and confirm the nine repositories derive rather than error. Expect a real diff for each — quite possibly a large one, since none has ever been reconciled against its files.

Treat the first diff for each as review material, not as work to apply. Every repository examined this way for the first time has produced findings.

Acceptance: fleet errors fall from nine to zero; each newly readable repository has its first diff reviewed before anything is applied.