repo-manager/workplans/RMGR-WP-0005-registrar-consolidation-deterministic-ids.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	parent_project	parent_workplan	related	state_hub_workstream_id
RMGR-WP-0005	workplan	Registrar consolidation and deterministic hub identifiers	infotech	repo-manager	active	codex	infotech	2026-08-17	2026-08-18	prj-state-hub-retirement	SHR-WP-0001	RMGR-WP-0004 STATE-WP-0080 STATE-WP-0068 CFED-WP-0001	7ddb5421-d960-4a3c-94b1-40b6c96abfab

Registrar consolidation and deterministic hub identifiers

Goal

Make hub identifiers stored in repository files derivable rather than database-local, so that any number of hub instances can reconcile the same repository without overwriting each other.

Implements ADR-007 decision 2: interim single-writer (A), target deterministic derivation (C2).

The defect

state_hub_workstream_id and state_hub_task_id are database-local primary keys stored in a shared git artifact. Two hub instances over two databases each mint their own value for the same workplan, and every sync overwrites the other.

Observed 2026-08-16 on STATE-WP-0080: workplan UUID 03f38314 from the workstation hub, bbfce36a from a second instance (404 against the workstation database), plus two disjoint sets of task UUIDs. Sync commits appear under both +0000 and +0200 timezones, confirming two machines write to one repository.

It also inverts ADR-001. Files are meant to originate work with the hub as read model; a file carrying a hub's private key is the file holding hub state.

Scope: 758 workplan files across the fleet currently carry these fields.

Apply the interim single-writer rule

id: RMGR-WP-0005-T01
status: done
priority: high
state_hub_task_id: "b57a6882-280d-4f0a-9c73-899843dfc3d3"

Until derivation ships, exactly one instance may write hub identifiers into repository files. The interim registrar is the automated production instance; workstation hubs are rebuildable caches (ADR-010 decision 2).

• Make the writeback path refuse to mint identifiers when the instance is not the registrar, rather than relying on operator discipline.
• Provide the configuration that designates the registrar, and make a non-registrar instance's read/project behaviour unchanged.
• Document the accepted cost: registration requires connectivity to the registrar, so disconnected work cannot register until T03 lands.

Interim, and deliberately so — it trades availability for correctness, and T03 removes the need for the trade.

Result (2026-08-18): repo_manager.registrar.is_identifier_registrar (STATEHUB_REGISTRAR env, else hostname prefix railiance). statehub fix-consistency skips C-06 / C-11 / C-32 mint+writeback when this instance is not the registrar. Read/project checks are unchanged. Cost documented in docs/repository-standards_v0.1.md.

The registrar was never stood up (found 2026-08-21). T01 shipped the guard — non-registrar instances correctly refuse to mint — but no instance satisfies the registrar condition, so nothing drains the queue. Twelve registrar-sync requests had accumulated from evidence-binder, kaizen-agentic, glas-harness and agentic-resources before anyone noticed.

Surveyed on railiance01, the designated production registrar:

Prerequisite	State
Registrar signal	fails — hostname is 239.62.205.92.host.secureserver.net, so the railiance* prefix heuristic never matches, and STATEHUB_REGISTRAR is unset
repo-manager clone	was absent; cloned 2026-08-21, rmgr installed into ~/.venvs/registrar
statehub CLI	not installable — pip install ~/state-hub fails ResolutionImpossible; hub-core installs, the conflict is elsewhere
Checkout ownership	999 files under ~/state-hub owned by root, because the state-hub pod bind-mounts /home/tegwick as a hostPath and runs as root. Blocks git pull and editable installs
Checkout lineage	points at gitea-remote, not forgejo-remote — the host was never swept by forgejo-tier3-remote-url-sweep-playbook. Its evidence-binder tracks a different lineage and cannot see EBIND-WP-0002 at all

The hostname heuristic is the cheapest fix and the most misleading defect: it reads as though a registrar exists whenever a host is named railiance*, but the production host is not. Prefer the explicit STATEHUB_REGISTRAR signal and treat the hostname fallback as unreliable, or drop it.

Two consequences beyond this task:

• Security. The state-hub pod mounts /home/tegwick and /home/tegwick/.ssh as hostPath volumes. A workload with the operator's private keys is a larger exposure than the registrar problem it surfaced.

• The remote sweep is incomplete, and this gates the registrar fix. Counted 2026-08-21:

  Host	forgejo-remote	gitea-remote
  workstation	126	0
  railiance01	7	70

  The two aliases are different servers — forgejo-remote is 92.205.62.239 (railiance01), gitea-remote is 92.205.130.254 (coulombcore) — and both are live. The workstation finished migrating; railiance01 did not. forgejo-tier3-remote-url-sweep-playbook still reads "Gitea remains canonical", which was true when written on 2026-07-04 and is now stale guidance.

Why the registrar cannot simply be switched on

The fix looked like one environment variable: the state-hub deployment has STATEHUB_REGISTRAR unset, and that pod is the real automated instance — it mounts /home/tegwick read-write, mounts /home/tegwick/.ssh at /root/.ssh for push, and carries STATE_HUB_SWEEP_HOSTNAME. Host-level provisioning was the wrong target.

Setting it today would be actively harmful. The pod would begin minting identifiers into 70 checkouts that track the superseded server and pushing them there — writing hub primary keys into a lineage nothing reads, and re-animating gitea-remote as a write target.

Required order:

1. Re-point railiance01's checkouts to forgejo-remote, keeping gitea as the rollback mirror the playbook specifies. Content diverges — evidence-binder there is at a715492 against the workstation's 9e3f4a6 — so this is a reconcile, not a URL rewrite.
2. Then set STATEHUB_REGISTRAR=1 on the deployment.

Reversing the order mints into the wrong lineage at fleet scale.

Open question worth answering first: the sweep pod is running now against those 70 stale checkouts. Establish what it has been pushing to gitea-remote before changing anything.

Re-register identifiers minted outside the registrar

id: RMGR-WP-0005-T02
status: wait
priority: medium
state_hub_task_id: "8e679ddb-9845-457f-8672-1fd4b7455e7b"

Records minted by non-registrar instances before T01 need reconciliation. Known cases, all created 2026-08-16/17 from the workstation hub:

• RMGR-WP-0004 (b8b3f1e0) and its seven tasks;
• CFED-WP-0001 (7a96da54) and its thirteen tasks, plus the prj-canon-federation repo record (3809b0ff);
• STATE-WP-0080 — already reconciled by hand to the second instance's IDs (bbfce36a), retained here as the worked example.

Prefer waiting for T03 where possible: once identifiers are derived, these converge without manual intervention. Re-register by hand only what blocks work before then.

Derive identifiers deterministically

id: RMGR-WP-0005-T03
status: todo
priority: high
state_hub_task_id: "28067729-498d-4f47-89bd-5b9718e999c7"

Replace minted UUIDs with UUIDv5 derived from the globally unique PREFIX-WP-NNNN identifier (and PREFIX-WP-NNNN-TNN for tasks).

• Fix the namespace UUID and derivation input as a published contract — the value must be reproducible by any implementation, not just this one.
• Field shape is unchanged, so consumers reading state_hub_workstream_id keep working; only the provenance of the value changes.
• Writeback becomes idempotent: two instances write identical bytes, so the flip-flop cannot recur regardless of how many hubs run.

Blocked on RMGR-WP-0004-T08. Deriving from a non-unique identifier manufactures collisions: two repositories sharing PRJ-WP- would compute the same UUID for different workplans. Uniqueness must be enforced first.

Unblocked 2026-08-21. RMGR-WP-0004-T08 closed 2026-08-18 (prefix registry plus rmgr prefix-uniqueness), and ADR-007 was amended the same day with the derivation scope this task needs:

• Derive for live records only; archived records keep frozen minted identifiers. This is what reconciles ADR-007 § Migration option 2 with the uniqueness derivation requires.
• Derivation input is (namespace, identifier) per ADR-011 decision 7. Namespace is the fleet branch, not the repository — the ecosystem is at N1, one implied namespace, so the pair does not disambiguate intra-namespace collisions and must not be read as if it did.
• Derivation is not retroactive: existing live records keep minted UUIDs until deliberately re-derived.
• Un-archiving is a collision hazard — a record returning to live must be checked against the live namespace and renumbered if it clashes. Build this check alongside derivation, not after.

Remaining prerequisite is the live-collision remediation below, tracked on RMGR-WP-0004-T09. 11 files, 5 identifiers.

Migrate the fleet

id: RMGR-WP-0005-T04
status: wait
priority: high
state_hub_task_id: "503a23a9-ede1-4cf1-bd32-e9669b84ce58"

One-time pass over the 758 files carrying hub identifiers: compute the derived value, update the database to match, and write the file.

• Must be all-or-nothing per repository — a half-migrated repo has some derived and some minted identifiers and reconciles unpredictably.
• Records whose current identifier is already referenced externally (dashboards, saved queries, progress events) need a mapping table from old to derived, kept as provenance rather than discarded.
• Repositories with unresolved identifier collisions cannot migrate until ADR-007 § Migration is ruled on; skip and report them rather than guessing.

Retire the interim rule

id: RMGR-WP-0005-T05
status: wait
priority: low
state_hub_task_id: "3946d1fc-2137-4d7b-a400-29b447ca83de"

Once derivation is live fleet-wide, remove the single-writer restriction from T01. Multiple hub instances become an availability choice rather than a correctness constraint, and disconnected registration works again.

Confirm before removal: two instances reconciling the same repository produce byte-identical writeback, and neither creates a duplicate record.

Rebuild local instances as caches

id: RMGR-WP-0005-T07
status: wait
priority: high
state_hub_task_id: "70f83359-0b61-4dc0-83b0-33f289b64e83"

Implement ADR-010 decisions 1–3: the central hub on railiance is authoritative as a reading of the repositories; local instances become rebuildable caches.

• A cache must be discardable and reconstructable from repository files alone, with no work lost.
• Local work must not require a hub — repository files are self-describing, so reading them is sufficient for working inside a repo.
• Cache reads are advisory and must carry their staleness (ADR-010 decision 8).

Measured 2026-08-17: 955 workplans locally against 649 on the primary, 320 local-only, of which 288 are backed by files that all exist on disk. That portion of the divergence is redundant and needs no merge — only a rebuild.

Separate file-derived from hub-native data

id: RMGR-WP-0005-T08
status: wait
priority: high
state_hub_task_id: "241cf058-2f3e-4d49-8cc9-5c714be4a1cf"

Implement ADR-010 decision 4. The two kinds need opposite handling:

• File-derived (workplans, tasks, statuses, dependencies) — central derives it and must not accept pushes of it (decision 5). Offline, the git commit is the write. No conflict model: conflicts are git conflicts.
• Hub-native (progress events, decisions, inbox messages, token events) — central owns it, needs a real write path and a local append-only buffer for replay. No conflict model either: append-only merges regardless of order.

Deliverable is an explicit classification of every record type the hub holds, with its truth source and offline behaviour, so neither kind is handled by the other's rules.

Feeds a rescope of STATE-WP-0068 (offline write buffer and edge relay): under this split most of what it buffers does not need buffering, and only the append-only stream does. Re-examine before building further on it — this likely reduces its scope.

Disposition the orphaned hub-first records

id: RMGR-WP-0005-T09
status: wait
priority: high
state_hub_task_id: "d40cc4a8-4280-4940-ac1d-dc1049f1b678"

28 records exist in the local instance with no backing file. They are the only records a cache rebuild would drop, so they must be classified first (ADR-010 § Orphan disposition):

1. Broken links — a file exists but backing_filename was never recorded. RMGR-WP-0004 is a confirmed instance. Repair the link; no data at risk. Likely the largest class, so classify before estimating the rest.
2. Live hub-first records — proposed/ready/backlog with no file, in activity-core, core-hub, hub-core, issue-core, ops-hub, prj-forgejo-org-refactor, railiance-enablement, railiance-infra, reef-railiance. Write a repository file or drop explicitly. These are ADR-001 violations and must not survive as hub-only records.
3. Closed hub-first records — finished/archived with no file. Retain as provenance where cheap; do not reconstruct completed plans.

Blocks T07 — rebuilding the cache before this classification would discard class 2.

Note: one of these records is already labelled SPURIOUS bootstrap (statehub register collision) in repo-manager, independent corroboration of the STATE-WP-0080 defect.

Assign one authoritative hub per record

id: RMGR-WP-0005-T10
status: wait
priority: medium
state_hub_task_id: "15f0f167-a8d0-4d5c-8576-3e93b1e8792f"

Implement ADR-010 decision 7. The retirement splits one hub into several, which is permitted only if every record has exactly one authoritative hub, determined by its repository and domain.

Define and enforce that mapping before the split lands. Without it the peer-database divergence this workplan exists to remove recurs at larger scale.

Coordinate with the hub-extension architecture in prj-state-hub-retirement/architecture/; hub-core owns the hub-native side.

Protect lifecycle status from automation

id: RMGR-WP-0005-T06
status: done
priority: medium
state_hub_task_id: "d440d59c-f78e-4752-84c7-f3d5fdf7d3c3"

Implement ADR-007 decision 3: an automated normalization pass may report lifecycle drift but may not promote a workplan from proposed to active. proposed means awaiting human review; automated promotion destroys the gate.

Observed: commit ff909e1 ("renormalize lifecycle state [auto]") promoted STATE-WP-0080 to active hours after it was drafted for review.

Extend the same protection to task status, where the symptom is currently sharper: C-15 forces CFED-WP-0001-T02 back to wait on every sync regardless of file content — reproduced three times, via file edit and via update_task_status, with the task never holding todo. Establish which direction wins for task status and make it consistent with ADR-001, where the file originates work.

Result (2026-08-18): In state-hub consistency: C-23 does not auto-promote proposed → active (report only). C-15 no longer writebacks wait over progress/todo; file wins via C-10 (ADR-001). C-15 remains a non-fixable warning when the DB is terminal and the file is not.