the-custodian/canon/architecture/coulomb-estate_v0.1.md

---
id: coulomb-estate-architecture
title: "Coulomb estate architecture"
status: proposed
owner: the-custodian
revision: "draft-3"
version: "0.1"
last_reviewed: "2026-08-31"
review_interval: 6m
---

# Coulomb estate — Software Architecture Documentation (arc42)

## 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.

---

## 1. Introduction 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

| Role | Concern |
| --- | --- |
| Operator | What must be discussed in person; ratification. |
| the-custodian | Canon, values, constitution, estate ADRs. |
| Product repos | Implementation and per-repo ADRs. |
| railiance-platform | Substrate: DNS, TLS, ingress, hosting. |
| policy-nexus | Publication only. |
| info-tech-canon | Semantic model, not this estate's building blocks. |

---

## 2. Architecture 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.

---

## 3. System 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

| Neighbour | Interface |
| --- | --- |
| Owning git repos | Source of workplans, ADRs, canon. |
| State Hub | Derived index / cache of those files. |
| policy.coulomb.social | Generated publication of canon and ADRs. |
| Railiance reef | Runtime for hubs, rApps, Forgejo. |
| NetKingdom | Identity, tenancy, IAM profile. |
| info-tech-canon | Imported semantics, not estate structure. |

---

## 4. Solution 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).

---

## 5. Building Block View

### 5.1 Level 1 – System/Top-Level

```text
                    ┌─────────────────────────┐
                    │     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.

---

## 6. Runtime View

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

---

## 7. Deployment View

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

---

## 8. Cross-Cutting Concepts

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

---

## 9. Architecture Decisions

Estate ADRs in `the-custodian/canon/architecture/`. Status is the source
front-matter.

| Id | Status | Decision |
| --- | --- | --- |
| `CUST-ADR-001` | accepted | File-backed work originates in repositories; the Hub projects it and separately owns declared Hub-native records. |
| `CUST-ADR-002` | accepted | Custodian agent runtime design. |
| `CUST-ADR-003` | accepted | Hub state is derived and fingerprint-invalidated. |
| `CUST-ADR-004` | accepted | Connectivity-first network posture. |
| `CUST-ADR-005` | accepted | Cross-repo work lives in a `prj-*` repo. |
| `CUST-ADR-006` | accepted | Three canons; import, do not redefine. |
| `CUST-ADR-007` | accepted | Namespace-aware work-record identity, deterministic Hub ids, and repository worker topology. |
| `adr-008` | superseded | Relocated to NetKingdom Tenancy Posture. |
| `CUST-ADR-010` | proposed | Two kinds of hub data; local cache vs authority. |
| `CUST-ADR-011` | proposed | Federated namespaces and reconciliation limits. |
| `CUST-ADR-012` | accepted | Forge is the projection source; unpushed working-copy state is preliminary. |

Related and published elsewhere: policy-nexus ADR-0001; Tenancy Posture
and IAM Profile v0.3 plus the current NetKingdom security standards;
NetKingdom ADR-0006–0008 and 0010–0015; railiance-master ADR-0001–0009;
activity-core ACT-ADR-001–007; ops-warden ADR-0001–0005 and 0007–0010;
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.

---

## 10. Quality Requirements

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

---

## 11. Risks and Technical Debt

N/A in this revision. Known residuals are the Forge-derived reset and
preliminary-overlay implementation under ADR-012. Markitect `arc42-v1` is not
registered yet.

---

## 12. Glossary

| Term | Meaning |
| --- | --- |
| Estate | The set of Coulomb / Custodian repos, canons, hubs, and rails. |
| Canon | Governing documents owned by one of the three federated canons. |
| Read model | A derived index. Never the origin of work or decisions. |
| Publication entry | One explicit object in policy-nexus `publication.json`. |
| First-wave complete | Chapters 1, 3, 4, 5.1, 9 and 12 are real; others real or N/A. |
| Project repo | A `prj-*` repo that coordinates cross-repo work (ADR-005). |