From 5b51623198d9959793762f447f5813960c0b5df8 Mon Sep 17 00:00:00 2001 From: codex Date: Tue, 18 Aug 2026 22:26:25 +0200 Subject: [PATCH] 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. --- canon/architecture/coulomb-estate_v0.1.md | 225 ++++++++++++++++++++++ 1 file changed, 225 insertions(+) create mode 100644 canon/architecture/coulomb-estate_v0.1.md diff --git a/canon/architecture/coulomb-estate_v0.1.md b/canon/architecture/coulomb-estate_v0.1.md new file mode 100644 index 0000000..babb37b --- /dev/null +++ b/canon/architecture/coulomb-estate_v0.1.md @@ -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). |