docs(cache): prove isolated projection rebuild
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a023c0-a0a3-7c03-b395-5a0d2757214d
This commit is contained in:
parent
6e9c93e7ca
commit
833fa6e746
3 changed files with 135 additions and 1 deletions
|
|
@ -5,7 +5,7 @@ title: "Repository projection cache rebuild"
|
|||
version: "1"
|
||||
status: active
|
||||
created: "2026-08-21"
|
||||
updated: "2026-08-21"
|
||||
updated: "2026-08-22"
|
||||
workplan_task: RMGR-WP-0005-T07
|
||||
---
|
||||
|
||||
|
|
@ -60,3 +60,30 @@ A database replacement is not authorized by this command. Before replacement:
|
|||
|
||||
The old database remains a recoverable source until those gates pass. Repo
|
||||
Manager does not merge database-local file-derived state back into repositories.
|
||||
|
||||
### Prove a file-derived rebuild in an empty projection
|
||||
|
||||
Use the registrar bootstrap only against a fresh or disposable State Hub whose
|
||||
projection for the target repository is empty:
|
||||
|
||||
```bash
|
||||
rmgr registrar-reconcile \
|
||||
--path /path/to/repository \
|
||||
--api-base http://127.0.0.1:58005 \
|
||||
--confirm-primary \
|
||||
--bootstrap-empty-projection
|
||||
```
|
||||
|
||||
The command requires a clean checkout synchronized with Forgejo and a healthy
|
||||
target. It refuses multi-repository or remote scans, proves that the selected
|
||||
repository has zero projected workplans before mutation, scopes registrar
|
||||
authority to the child consistency process, and then verifies every
|
||||
authoritative workplan, task, intake, and decision UUID. It restores the
|
||||
generated `.custodian-brief.md` if that is the only checkout change and fails
|
||||
closed on any authoritative file mutation.
|
||||
|
||||
Run a second read-only consistency pass against the same target. A passing
|
||||
rebuild has no issues and has the same record identifiers, lifecycle statuses,
|
||||
and source bindings as the files. This operation deliberately does not copy
|
||||
progress events, token events, or messages; those hub-native records must pass
|
||||
their own central-owner gate before any legacy database is discarded.
|
||||
|
|
|
|||
88
docs/evidence/RMGR-WP-0005-isolated-rebuild-2026-08-22.md
Normal file
88
docs/evidence/RMGR-WP-0005-isolated-rebuild-2026-08-22.md
Normal file
|
|
@ -0,0 +1,88 @@
|
|||
---
|
||||
id: RMGR-EVIDENCE-0005-ISOLATED-REBUILD
|
||||
type: evidence
|
||||
title: "RMGR-WP-0005 isolated repository projection rebuild"
|
||||
status: accepted
|
||||
created: "2026-08-22"
|
||||
updated: "2026-08-22"
|
||||
workplan_task: RMGR-WP-0005-T07
|
||||
observed_at: "2026-08-22T10:27:59Z"
|
||||
---
|
||||
|
||||
# RMGR-WP-0005 isolated repository projection rebuild
|
||||
|
||||
## Result
|
||||
|
||||
The file-derived half of the cache-replacement gate passes for `repo-manager`.
|
||||
The hub-native centralization half does not yet pass, so neither the workstation
|
||||
database nor the remaining production projection may be discarded on this
|
||||
evidence.
|
||||
|
||||
## Disposable proof environment
|
||||
|
||||
- PostgreSQL 16 container: `state-hub-rmgr-t07-20260822`
|
||||
- database endpoint: `127.0.0.1:55439`
|
||||
- State Hub API: `127.0.0.1:58005`
|
||||
- schema head: `b8d4f0a2c6e1`
|
||||
- fresh repository projection UUID: `f5632ed0-ef39-444a-a9bd-232eff9d6221`
|
||||
- Repo Manager implementation: `707fb85`, `6e9c93e`
|
||||
- State Hub implementation: `03c7924`, `059de93`
|
||||
|
||||
The database was recreated from an empty PostgreSQL database, migrated to head,
|
||||
and seeded. Before the governed bootstrap, the target repository had zero
|
||||
workplans. The bootstrap was invoked with:
|
||||
|
||||
```bash
|
||||
rmgr registrar-reconcile \
|
||||
--path /home/worsch/repo-manager \
|
||||
--api-base http://127.0.0.1:58005 \
|
||||
--confirm-primary \
|
||||
--bootstrap-empty-projection
|
||||
```
|
||||
|
||||
The command returned `applied`, correlation ID
|
||||
`c98c37d4-5ad0-4090-a216-325e4ebaa5c9`, and verified no missing identifiers.
|
||||
|
||||
| Authoritative record | Files | Rebuilt projection | Missing |
|
||||
| --- | ---: | ---: | ---: |
|
||||
| Workplans | 9 | 9 | 0 |
|
||||
| Tasks | 62 | 62 | 0 |
|
||||
| Intakes | 2 | 2 | 0 |
|
||||
| Decisions | 0 | 0 | 0 |
|
||||
|
||||
A second read-only consistency pass reported no issues, `9/9` source bindings,
|
||||
zero failures, zero warnings, and result `pass`. The checkout remained clean and
|
||||
synchronized with `origin/main`. This proves that an empty projection can retain
|
||||
the repository's existing authoritative UUIDs rather than mint database-local
|
||||
replacements.
|
||||
|
||||
## Hub-native centralization gate
|
||||
|
||||
The disposable projection correctly contained zero progress events, token
|
||||
events, and agent messages: none of those records is reconstructed from files.
|
||||
A read-only database comparison found:
|
||||
|
||||
| Record set | Workstation hub | Production central hub |
|
||||
| --- | ---: | ---: |
|
||||
| Repo-linked progress events | 35 | 2 |
|
||||
| Repo-linked token events | 0 | 0 |
|
||||
| Messages to/from `repo-manager` | 13 | 0 |
|
||||
|
||||
The workstation also still contains ten Repo Manager workplan rows: the nine
|
||||
file-backed records plus one closed, unbound legacy duplicate of
|
||||
`RMGR-WP-0001`. Production currently holds only the governed `RMGR-WP-0005`
|
||||
pilot and its 12 tasks. These counts are observations, not a claim that every
|
||||
row can be copied directly: progress events need stable idempotent replay, while
|
||||
mutable message state requires its owner-specific ordered command contract.
|
||||
|
||||
Therefore T07 remains `progress`. The exact remaining gate is to migrate or
|
||||
otherwise disposition the 35 workstation progress events and 13 message records
|
||||
at their declared central owner, then repeat the comparison before replacing
|
||||
the legacy workstation database. The isolated rebuild performs no such transfer
|
||||
and authorizes no production mutation.
|
||||
|
||||
## Cleanup
|
||||
|
||||
The API and disposable database container were removed after capturing this
|
||||
evidence. The environment contained projections only and is intentionally not a
|
||||
recoverable source of work.
|
||||
|
|
@ -480,6 +480,25 @@ the pilot record without identifier writeback. T07 remains in progress because
|
|||
the full isolated projection rebuild and hub-native centralization proof still
|
||||
cover more than this one workplan.
|
||||
|
||||
**Full isolated rebuild (2026-08-22):** the guarded
|
||||
`--bootstrap-empty-projection` path rebuilt a fresh disposable State Hub from
|
||||
the repository's existing authoritative identifiers: 9 workplans, 62 tasks,
|
||||
2 intakes, and 0 decisions, with no missing records. A second read-only pass
|
||||
reported zero issues and all 9 source bindings synchronized. The path refuses a
|
||||
non-empty target projection, multi-repository scans, unsynchronized Forgejo
|
||||
checkouts, and any authoritative file mutation. State Hub commits `03c7924`
|
||||
and `059de93`; Repo Manager commits `707fb85` and `6e9c93e`.
|
||||
|
||||
The remaining gate is now measured rather than inferred. The workstation hub
|
||||
has 35 Repo Manager-linked progress events and 13 messages to/from
|
||||
`repo-manager`; production has 2 and 0 respectively. The disposable rebuild has
|
||||
zero of each by design. These hub-native records cannot be reconstructed from
|
||||
files, and mutable message state cannot use unordered append replay. T07 stays
|
||||
`progress` until the declared central owner migrates or dispositions them and a
|
||||
repeat comparison passes. Evidence and the non-destructive procedure are in
|
||||
`docs/evidence/RMGR-WP-0005-isolated-rebuild-2026-08-22.md` and
|
||||
`docs/cache-rebuild_v1.md`.
|
||||
|
||||
## Separate file-derived from hub-native data
|
||||
|
||||
```task
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue