Coulomb estate architecture

About this document

This is the first-wave estate map. It describes how the Coulomb / Custodian estate is put together: canons, hubs, rails, and publication. System-level arc42 documents (Railiance, NetKingdom, State Hub, Policy Nexus) live in their owning repos. Chapter 9 lists estate ADRs; it does not paste them.

01Introduction and Goals

the-custodian holds meaning, boundaries, and continuity for a local-first agent estate. Implementation lives in product repos. Coordination state is a read-model of repository files, not the origin of those files.

1.1 Requirements Overview

• Work, decisions, and canon originate as files in the owning repo.
• A publication surface keeps governing documents at permanent URLs.
• Runtime (Rails, rApps, identity, storage) is consumed from platform packages, not reimplemented in the custodian.
• Cross-repo work is coordinated, not owned, by a dedicated project repo when it does not belong to one product.

1.2 Quality Goals

1. Rebuildability — State Hub can be reconstructed from registered repository files (ADR-001).
2. Concept ownership — canons import, they do not redefine (ADR-006).
3. Permanence of published policy addresses (policy-nexus ADR-0001).
4. Honest currency — stale documents are visibly stale.

1.3 Stakeholders

02Architecture Constraints

N/A in this revision — local-first files, no second source of truth, stdlib-preferring tooling, single-node rail availability. To be written as first-wave complete.

03System Scope and Context

In: estate canon (constitution, standards, architecture ADRs), the federation of canons, the publication contract, the hub-as-read-model rule, and the map of first-wave systems.

Out: product implementation, InfoTechCanon's landscape model, regulatory intake (risk-nexus), and per-system deployment detail (those belong in the system arc42).

3.1 Business Context

The estate is a set of repositories that together run Coulomb products and the agent work-factory. Readers need one map of what governs what. Owners need a place that is not also the implementation.

3.2 Technical Context

04Solution Strategy

• Files first. Workplans and ADRs are markdown in git. The hub rebuilds from them (ADR-001, ADR-003).
• One registrar. Workplan identifiers are globally unique; this workstation is not the registrar (ADR-007).
• Three canons, federated. Custodian (governance), InfoTechCanon (information-system semantics), CommerceCanon (counterparty semantics). They import, they do not redefine (ADR-006).
• Publish, do not author. policy-nexus reads owning repos and emits static addresses. It never writes back.
• Project repos for cross-repo work (prj-*), not an unbound hub workplan (ADR-005).

05Building Block View

5.1 Level 1 – System/Top-Level

                    ┌─────────────────────────┐
                    │     the-custodian       │
                    │  constitution, values,  │
                    │  estate ADRs, memory    │
                    └────────────┬────────────┘
           ┌─────────────────────┼─────────────────────┐
           ▼                     ▼                     ▼
   ┌───────────────┐    ┌────────────────┐    ┌─────────────────┐
   │ info-tech-    │    │ commerce-canon │    │ net-kingdom     │
   │ canon         │    │                │    │ (identity /     │
   │ (semantics)   │    │                │    │  tenancy)       │
   └───────────────┘    └────────────────┘    └────────┬────────┘
                                                       │
   ┌───────────────┐    ┌────────────────┐             │
   │ state-hub     │◄───│ product repos  │◄────────────┘
   │ (read model)  │    │ + project repos│
   └───────────────┘    └────────┬───────┘
                                 │
                    ┌────────────┴────────────┐
                    ▼                         ▼
           ┌────────────────┐        ┌─────────────────┐
           │ railiance      │        │ policy-nexus    │
           │ (reef, rApps)  │        │ (publication)   │
           └────────────────┘        └─────────────────┘

5.2 Level 2 – Key Components

N/A in this revision.

5.3 Level 3 – Internal Structure (as needed)

N/A in this revision.

06Runtime View

N/A — estate coordination is file sync plus hub rebuild, not a single runtime scenario. System runtimes belong in their own arc42.

07Deployment View

N/A — Railiance owns where things run. This document names the substrate; it does not map nodes.

08Cross-Cutting Concepts

N/A in this revision. Concept ownership and the hub/cache split are already in §4 and the ADRs in §9.

09Architecture Decisions

Estate ADRs in the-custodian/canon/architecture/. Publication ids still need repo prefixes (WP-0003). Status is the source front-matter.

Related and published elsewhere: policy-nexus ADR-0001; Tenancy Posture and IAM Profile v0.3; railiance-master ADR-0001–0008; activity-core ACT-ADR-001–005; ops-warden ADR-0001–0005; railiance-platform RPLAT-ADR-0001–0003.

Unresolved WP-0003 conflicts (hosts/infra duplicate ADR-003/004, coulomb-social ADR-0002 partial supersession) are not listed as current.

10Quality Requirements

N/A in this revision — rebuildability and currency already have mechanical checks (fix-consistency, make currency).

11Risks and Technical Debt

N/A in this revision. Known residual: this workstation cannot mint hub UUIDs (ADR-007 registrar). Markitect arc42-v1 is not registered yet.

12Glossary