coulomb/the-custodian
4
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions

docs(canon): ADR-007 accepted — deterministic hub IDs (C2) with single-writer interim

Browse source 
Decision 2 reframed: the defect is a database-local key stored in a shared
artifact, which also inverts ADR-001. Target is UUIDv5 derived from the
globally unique PREFIX-WP-NNNN, making writeback idempotent across any
number of hub instances. Prerequisite: decision 1 uniqueness must be
enforced first, or derivation from PRJ-WP- style collisions manufactures
duplicate UUIDs.

Interim: one writer only, the automated production instance. Rejected:
collapsing to a shared database, which kills offline capability against
STATE-WP-0068. Both land in repo-manager per 747011c6.

Migration scope: 758 workplan files carry these fields. Remediation of the
3 shared prefixes and 5 duplicated identifiers stays an open ruling.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
codex 2026-08-17 10:17:58 +02:00
parent 4565bef819
commit dd65c91b4f
1 changed files with 50 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

60
canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md
View file

@ -2,9 +2,10 @@
id: ADR-007
type: architecture-decision-record
title: "Workplan Identity Uniqueness, Single Registrar, and Repo Worker Topology"
status: proposed
status: accepted
decided_by: Bernd Worsch
date: "2026-08-16"
accepted: "2026-08-17"
tags: ["architecture", "workplans", "identity", "state-hub", "repo-manager", "agents", "registrar"]
---
@ -12,8 +13,12 @@ tags: ["architecture", "workplans", "identity", "state-hub", "repo-manager", "ag
## Status
Proposed. Remediation of existing collisions (§ Migration) needs a separate
ruling before execution — it is disruptive and touches six repositories.
Accepted 2026-08-17. Identifier uniqueness, the registrar model, lifecycle
protection, and worker topology are settled.
**Remediation of existing collisions (§ Migration) remains an open ruling.** It
is disruptive, touches six repositories, and no active work depends on it — all
five duplicated identifiers are `finished`.
## Context
@ -76,14 +81,49 @@ one workplan across the entire fleet, for all time.
- Prefixes are derived from the *project or repository identity*, never from a
flavor marker or category (`PRJ-WP-` is invalid by construction).
**2. Exactly one registrar writes hub identifiers into repository files.** A
single instance is authoritative for registration and ID writeback. Other
instances may read, project, and serve; they must not mint workplan or task
UUIDs into git-tracked files.
**2. Hub identifiers stored in repository files must be derivable, not
database-local.** The defect is structural: a database-local key is stored in a
shared artifact, so each database overwrites the other's value on every sync.
It also inverts ADR-001 — a file carrying a hub's private key is the file
holding hub state.
The workstation hub is a development read replica, not a registrar. Running
`fix-consistency` with writeback from a workstation against a repository whose
primary is elsewhere is the mechanism that produced the flip-flop.
*Target state (C2).* `state_hub_workstream_id` and `state_hub_task_id` become
**deterministic**: UUIDv5 derived from the globally unique `PREFIX-WP-NNNN`
identifier. Every instance computes the same value independently, writeback
becomes idempotent, and any number of hub instances may coexist without
coordination. The field shape is unchanged, so consumers keep working; only the
provenance of the value changes.
This has a hard prerequisite: deterministic derivation from a **non-unique**
identifier would manufacture collisions rather than remove them. Two project
repos sharing `PRJ-WP-` would compute the same UUID for different workplans.
Decision 1 must therefore be enforced before derivation ships.
*Interim state (A).* Until derivation lands, exactly one instance writes hub
identifiers into repository files. Other instances may read, project, and serve,
but must not mint workplan or task UUIDs into git-tracked files. The interim
registrar is the automated production instance; workstation hubs are development
read replicas.
The interim is policy, enforced by discipline, and it has a real cost:
registration requires connectivity to the registrar, so disconnected work cannot
register. That cost is accepted only until C2 removes the need for it, at which
point the number of hub instances becomes an availability choice rather than a
correctness constraint.
*Rejected.* Collapsing to a single shared database (workstation hubs pointing at
the production database) would also make identifiers consistent by construction,
but it eliminates offline capability — cutting directly against `STATE-WP-0068`
(offline write buffer and edge relay) — and couples all local work to tunnel
availability.
*Ownership.* Both the interim guard and the derivation belong to `repo-manager`
under decision `747011c6`, which already places file-backed record indexing and
reconciliation there. Building either in `state-hub` would invest in a component
being retired under `STATE-WP-0079`.
Migration scope for C2: **758 workplan files** across the fleet currently carry
these fields.
**3. Lifecycle status is not automatically promoted.** An automated
normalization pass may report drift; it may not move a workplan from `proposed`