---
id: STATE-WP-0086
type: workplan
title: "Fast single-repository forge projection reconciliation"
domain: infotech
repo: state-hub
status: finished
owner: codex
topic_slug: infotech
created: "2026-08-30"
updated: "2026-08-30"
related:
  - STATE-WP-0083
  - RMGR-WP-0005
  - RMGR-WP-0012
state_hub_workstream_id: "c43b1b2c-2f84-540a-9b93-03a13ed148f1"
---

# Fast single-repository forge projection reconciliation

## Goal

Expose the existing forge-derived repository reset as a guarded, idempotent,
single-request compatibility API. The central hub reads the exact pushed forge
commit itself and applies workplan/task changes in one database transaction.

## Guarded exact-commit API

```task
id: STATE-WP-0086-T01
status: done
priority: high
state_hub_task_id: "1b72b4e2-419a-5b55-91a7-3f56afba7480"
```

Add a primary-only endpoint that derives one repository from Forgejo, compares
the derived commit with the caller's expected commit, and commits or rolls back
the complete repository reconciliation atomically.

## Complete task and workplan field projection

```task
id: STATE-WP-0086-T02
status: done
priority: high
state_hub_task_id: "25e1a146-47b2-5704-af45-b314c5a5a353"
```

Carry owner, priority, description, blocking, and human-intervention fields
through the existing forge derivation and update path without weakening its
collision, unreadable-source, or retirement safeguards.

## Idempotency, regression, and performance proof

```task
id: STATE-WP-0086-T03
status: done
priority: high
state_hub_task_id: "88723069-59d4-5b7e-85a4-36c3575382af"
```

Test wrong-instance rejection, commit mismatch, replay, transactional rollback,
ad-hoc creation, task updates, and bounded request count. Document the endpoint
as the fast path while retaining the full consistency checker for deep audits.

Focused projection tests are green, including idempotent replay and exact-commit
refusal. Helm revision 50 deployed `main-34f5cb3`; the live primary reconciled
exact commit `b97cfbb2b123f101729556288a638a8e5dd271e3` in two requests and
6242.4 ms, updating 54 workplans and 68 tasks with no retirement or refusal.