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