From dd65c91b4fcb1a9c5a7d80afa64553f54e1397d0 Mon Sep 17 00:00:00 2001 From: codex Date: Mon, 17 Aug 2026 10:17:58 +0200 Subject: [PATCH] =?UTF-8?q?docs(canon):=20ADR-007=20accepted=20=E2=80=94?= =?UTF-8?q?=20deterministic=20hub=20IDs=20(C2)=20with=20single-writer=20in?= =?UTF-8?q?terim?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- ...kplan-identity-and-repo-worker-topology.md | 60 +++++++++++++++---- 1 file changed, 50 insertions(+), 10 deletions(-) diff --git a/canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md b/canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md index ddf2e08..afffb47 100644 --- a/canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md +++ b/canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md @@ -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`