4039c9d1c0
Prefix CUST-ADR-001–011 and record owner, revision, and review dates so policy-nexus can publish them. Estate arc42 chapter 9 updated.
227 lines
8.7 KiB
Markdown
227 lines
8.7 KiB
Markdown
---
|
||
id: coulomb-estate-architecture
|
||
title: "Coulomb estate architecture"
|
||
status: proposed
|
||
owner: the-custodian
|
||
revision: "draft-2"
|
||
version: "0.1"
|
||
last_reviewed: "2026-08-19"
|
||
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/`. Publication ids
|
||
still need repo prefixes (WP-0003). Status is the source front-matter.
|
||
|
||
| Id | Status | Decision |
|
||
| --- | --- | --- |
|
||
| `CUST-ADR-001` | accepted | Workplans and tasks originate as repo files; the hub is a read model. |
|
||
| `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 | Globally unique workplan ids; one registrar. |
|
||
| `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. |
|
||
|
||
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.
|
||
|
||
---
|
||
|
||
## 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 residual: this workstation cannot mint hub
|
||
UUIDs (ADR-007 registrar). 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). |
|