the-custodian/canon/architecture/adr-009-federated-namespaces-and-reconciliation-limits.md

id	type	title	status	decided_by	date	tags
ADR-009	architecture-decision-record	Federated Namespaces, Qualified Identifiers, and the Limits of Reconciliation	proposed	Bernd Worsch	2026-08-17	architecture federation namespace identity reconciliation fos adr-007 adr-008

ADR-009: Federated Namespaces, Qualified Identifiers, and the Limits of Reconciliation

Status

Proposed. Amends ADR-007 decision 1 and extends ADR-008 decision 4.

Context

The ecosystem must be federation-capable — able to work without a live link to central services — and chain-of-command efficient. These read as opposing requirements, but federated-organization-standard_v1.0 already resolves the organizational half:

global coherence is achieved through policy, escalation, and shared protocols rather than through monolithic control (:51)

bounded autonomy plus disciplined coordination (:86)

Authority is a policy layer; availability is a mechanism. Nothing requires the mechanism to depend on reaching the authority — the same separation distributed version control makes, where an integration branch is privileged by agreement rather than by any technical property.

One accepted decision does violate this. ADR-007 decision 1 requires running numbers that are globally unique and allocated forward only. Global sequential allocation requires a coordinator — precisely the central dependency federation must survive. Two disconnected forks each allocating RCLUSTER-WP-0015 is not an edge case but a certainty.

This is not hypothetical. Instance-per-client tenancy (CUST-WP-0058) already means each client deployment is a fork of the stack; the business model committed to forking before the identifier scheme could express it.

Decision

1. Records live in a namespace. A namespace is a federated branch of the ecosystem — a fleet instance, a client deployment, an autonomous domain that may operate disconnected. It is the unit of sovereignty in FOS terms, and the unit of divergence here.

2. Identifiers are unique within a namespace, qualified across namespaces. ADR-007 decision 1 is amended: uniqueness and forward-only allocation are namespace-scoped, not global. Global identity is the pair (namespace, identifier).

Notation is a suffix:

RCLUSTER-WP-0015              this namespace — the common case, unchanged
RCLUSTER-WP-0015@railiance01  a foreign namespace, explicitly qualified

Unqualified always means "in my own namespace", exactly as main does against origin/main. A suffix keeps existing sorting, grep, and tooling working; a prefix would break them.

3. Deterministic identifiers derive from the pair. ADR-007 decision 2 (C2) derives UUIDv5 from PREFIX-WP-NNNN. Under federation the derivation input must be (namespace, identifier). Deriving from the identifier alone would make two forks holding unrelated work under the same number compute the same UUID — a collision manufactured by the fix. C2 is not yet built, so this is free now and expensive later.

4. Records carry lineage. A namespace records what it forked from and at what point; a record forked from another namespace records its origin. Without lineage, a shared identifier is ambiguous between the same work, diverged and different work, colliding — a distinction that cannot be reconstructed after the fact.

5. Mutable state is derived from an append-only log. Extending ADR-008 decision 4: status and other mutable fields are a fold over append-only events rather than fields to be reconciled. Reconciliation then becomes union-of-events plus re-derivation — deterministic, order-independent, and requiring no conflict model. This collapses the hardest part of reconciliation into the part that was already free.

6. Coexistence is the normal case; merging is the exception. The qualifier is primarily a coexistence mechanism, not merge preparation. Most forks — client instances above all — are never intended to return. The architecture must support permanent parallel operation as a first-class outcome, not as a failure to reconcile.

7. What may fork. Canon, plans, knowledge, and records fork freely. Effects do not. Two namespaces may hold divergent plans about one production database; they cannot hold divergent production databases. Work that acts on shared operational infrastructure is not fork-safe and must be coordinated through the owning namespace.

Reconciliation tiers, and where automation stops

Tier	Situation	Mechanism	Automatable
T0 Fork	namespace created, lineage recorded	metadata	yes
T1 Sync	pull canon, plans, or knowledge from another namespace	append events, re-derive	largely
T2 Reintegration	fork returns; records diverged, no independent operational infrastructure	union events, re-derive, human-resolve genuine contradictions	partly
T3 Amalgamation	distinct operational infrastructure, identity, credentials, data stores, possibly distinct canon	governed programme — see below	no

The T2/T3 test is whether the fork established its own operational infrastructure — stateful systems with independently diverged state.

T3 is not a merge. It resembles the merger or acquisition of distinct companies far more than a version-control merge, and must be planned as such:

• due diligence — inventory both sides, item by item;
• survivor decisions per subsystem — keep, move, replace, retire;
• migration with evidence, and decommissioning of what does not survive;
• governance integration — reconciling two bodies of canon is a human act, never automated;
• identity, credential, and data custody consolidation.

T3 may legitimately end without integration. Permanent coexistence, or divestment, are valid outcomes. Real mergers most often fail at systems integration; an architecture that assumes eventual convergence is lying about its own limits.

Known cost

prj-state-hub-retirement is a T3 reconciliation inside a single organization — two hub implementations with distinct infrastructure. It required a dedicated project repository, a 425-item disposition inventory (SHR-INV-0001), staged migration with strangler adapters, and explicit retirement gates. That is the realistic cost of T3 under the most favourable possible conditions: one owner, one canon, one credential authority.

Nothing in this ADR reduces that cost. It ensures the cost is visible before a fork is created rather than discovered when reconciliation is attempted.

Consequences

Positive. Disconnected operation stops requiring a coordinator for identity. ADR-007 decision 1's contradiction is resolved rather than tolerated. Client instances become expressible. Reconciliation limits are stated rather than implied.

Negative. Every record gains a namespace and lineage, and tooling must learn qualified references. The fork-boundary rule (decision 7) constrains what disconnected work may legitimately do — deliberately.

Deferred. Merge machinery for T2 is not specified here and should not be built until a real fork exists and needs it. T3 needs no machinery by definition; it needs a project repository and human judgement.

Amended. ADR-007 decision 1 — uniqueness is namespace-scoped, not global. ADR-007 decision 2 — derivation input becomes (namespace, identifier).

Open question

What is the namespace boundary in practice? Candidates: a fleet instance (railiance01), a client deployment, or an FOS autonomous domain. FOS's recursion ("from projects to companies to foundation-like umbrella structures") suggests namespaces nest, which would make qualification relative rather than absolute. Settle before implementation; the notation works either way.

References

• canon/standards/federated-organization-standard_v1.0.md — bounded autonomy, escalation, sovereignty by default, rebuildability
• ADR-001 — workplans originate as repo files
• ADR-007 — identifier uniqueness and derived identifiers (amended here)
• ADR-008 — hub authority, local cache, and the two kinds of hub data
• CUST-WP-0058 — instance-per-client tenancy
• SHR-INV-0001 — 425-item disposition inventory, T3 cost evidence