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