From 833fa6e746c7eae9155d09938403e4b7f1c46b81 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sat, 22 Aug 2026 12:31:35 +0200 Subject: [PATCH] docs(cache): prove isolated projection rebuild Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a023c0-a0a3-7c03-b395-5a0d2757214d --- docs/cache-rebuild_v1.md | 29 +++++- ...MGR-WP-0005-isolated-rebuild-2026-08-22.md | 88 +++++++++++++++++++ ...gistrar-consolidation-deterministic-ids.md | 19 ++++ 3 files changed, 135 insertions(+), 1 deletion(-) create mode 100644 docs/evidence/RMGR-WP-0005-isolated-rebuild-2026-08-22.md diff --git a/docs/cache-rebuild_v1.md b/docs/cache-rebuild_v1.md index f159c7f..d51a053 100644 --- a/docs/cache-rebuild_v1.md +++ b/docs/cache-rebuild_v1.md @@ -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. diff --git a/docs/evidence/RMGR-WP-0005-isolated-rebuild-2026-08-22.md b/docs/evidence/RMGR-WP-0005-isolated-rebuild-2026-08-22.md new file mode 100644 index 0000000..f2f481e --- /dev/null +++ b/docs/evidence/RMGR-WP-0005-isolated-rebuild-2026-08-22.md @@ -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. diff --git a/workplans/RMGR-WP-0005-registrar-consolidation-deterministic-ids.md b/workplans/RMGR-WP-0005-registrar-consolidation-deterministic-ids.md index 328fc91..d034a0b 100644 --- a/workplans/RMGR-WP-0005-registrar-consolidation-deterministic-ids.md +++ b/workplans/RMGR-WP-0005-registrar-consolidation-deterministic-ids.md @@ -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