coulomb/the-custodian
4
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions
the-custodian/canon/architecture/coulomb-estate_v0.1.md
codex 4039c9d1c0
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 1s
Details
Add publication ids and metadata to estate ADRs 
Prefix CUST-ADR-001–011 and record owner, revision, and review dates
so policy-nexus can publish them. Estate arc42 chapter 9 updated.
2026-08-19 01:09:18 +02:00

8.7 KiB
Raw Blame History

id title status owner revision version last_reviewed review_interval
coulomb-estate-architecture Coulomb estate architecture proposed the-custodian draft-2 0.1 2026-08-19 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

                    ┌─────────────────────────┐
                    │     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).