Add first-wave Coulomb estate arc42 map
One document for the estate building-block view. Chapter 9 indexes the existing architecture ADRs; policy-nexus will publish it.
This commit is contained in:
codex
parent
47b2843df4
commit
5b51623198
1 changed files with 225 additions and 0 deletions
225
canon/architecture/coulomb-estate_v0.1.md
Normal file
225
canon/architecture/coulomb-estate_v0.1.md
Normal file
|
|
@ -0,0 +1,225 @@
|
||||||
|
---
|
||||||
|
id: coulomb-estate-architecture
|
||||||
|
title: "Coulomb estate architecture"
|
||||||
|
status: proposed
|
||||||
|
owner: the-custodian
|
||||||
|
revision: "draft-1"
|
||||||
|
version: "0.1"
|
||||||
|
last_reviewed: "2026-08-18"
|
||||||
|
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.
|
||||||
|
|
||||||
|
| Source | Status | Decision |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `adr-001-workplans-as-repo-artefacts.md` | accepted | Workplans and tasks originate as repo files; the hub is a read model. |
|
||||||
|
| `adr-002-custodian-agent-runtime-design.md` | accepted | Custodian agent runtime design. |
|
||||||
|
| `adr-003-materialized-derived-state.md` | accepted | Hub state is derived and fingerprint-invalidated. |
|
||||||
|
| `adr-004-connectivity-first-network-posture.md` | accepted | Connectivity-first network posture. |
|
||||||
|
| `adr-005-cross-repo-workplans-project-repos.md` | accepted | Cross-repo work lives in a `prj-*` repo. |
|
||||||
|
| `adr-006-canon-federation-concept-ownership.md` | accepted | Three canons; import, do not redefine. |
|
||||||
|
| `adr-007-workplan-identity-and-repo-worker-topology.md` | accepted | Globally unique workplan ids; one registrar. |
|
||||||
|
| `adr-008-multi-tenancy-model.md` | superseded | Relocated to NetKingdom Tenancy Posture. |
|
||||||
|
| `adr-010-hub-authority-and-local-cache-model.md` | proposed | Two kinds of hub data; local cache vs authority. |
|
||||||
|
| `adr-011-federated-namespaces-and-reconciliation-limits.md` | proposed | Federated namespaces and reconciliation limits. |
|
||||||
|
|
||||||
|
Related, not estate-owned: policy-nexus ADR-0001 (addressing), NetKingdom
|
||||||
|
Tenancy Posture (published), railiance-master ADR-0001–0008 (published).
|
||||||
|
|
||||||
|
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). |
|
||||||
Loading…
Add table
Add a link
Reference in a new issue