From 25dd59a7c6af322ad04842416f7140c3c2f5f9ae Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 19 Aug 2026 01:09:41 +0200 Subject: [PATCH] Publish estate ADRs, platform ADRs, and IAM Profile v0.3 T04 classifies the remaining corpus. Chapter 9 on the first-wave arc42 stubs now matches what is published. --- .../addressing-and-permanence/v1/index.html | 6 +- .../adr/custodian-agent-runtime/v1/index.html | 242 +++ .../v1/revisions/accepted-1/index.html | 242 +++ .../custodian-canon-federation/v1/index.html | 253 +++ .../v1/revisions/accepted-1/index.html | 253 +++ .../v1/index.html | 236 +++ .../v1/revisions/accepted-1/index.html | 236 +++ .../v1/index.html | 225 +++ .../v1/revisions/accepted-1/index.html | 225 +++ .../v1/index.html | 284 ++++ .../v1/revisions/draft-2/index.html | 284 ++++ .../adr/custodian-hub-authority/v1/index.html | 238 +++ .../v1/revisions/draft-1/index.html | 238 +++ .../v1/index.html | 244 +++ .../v1/revisions/accepted-1/index.html | 244 +++ .../custodian-workplan-identity/v1/index.html | 278 +++ .../v1/revisions/accepted-1/index.html | 278 +++ .../v1/index.html | 298 ++++ .../v1/revisions/accepted-1/index.html | 298 ++++ .../v1/index.html | 211 +++ .../v1/revisions/1.0/index.html | 211 +++ .../v1/index.html | 6 +- .../v1/index.html | 6 +- .../v1/index.html | 212 +++ .../v1/revisions/1.0/index.html | 212 +++ .../v1/index.html | 6 +- .../v1/index.html | 6 +- .../v1/index.html | 6 +- .../v1/index.html | 6 +- .../v1/index.html | 6 +- .../railiance-repository-prefix/v1/index.html | 6 +- .../v1/index.html | 209 +++ .../v1/revisions/1.0/index.html | 209 +++ .../coulomb-estate/v0.1/index.html | 12 +- .../v0.1/revisions/draft-2/index.html | 274 +++ .../architecture/net-kingdom/v0.1/index.html | 10 +- .../v0.1/revisions/draft-2/index.html | 244 +++ .../architecture/policy-nexus/v0.1/index.html | 6 +- build/architecture/railiance/v0.1/index.html | 9 +- .../v0.1/revisions/draft-2/index.html | 246 +++ build/architecture/state-hub/v0.1/index.html | 10 +- .../v0.1/revisions/draft-2/index.html | 246 +++ build/index.html | 2 +- build/publication-manifest.json | 291 +++- build/standards/iam-profile/v0.3/index.html | 319 ++++ .../iam-profile/v0.3/revisions/0.3/index.html | 319 ++++ .../standards/tenancy-posture/v0.1/index.html | 6 +- docs/adr-review/SUMMARY.md | 23 +- docs/adr-review/ledger.json | 1508 ++++++++++------- docs/adr-review/rulings.json | 692 +++++++- publication.json | 107 ++ source-inventory.json | 100 +- ...EXUS-WP-0003-adr-review-cleanup-publish.md | 12 +- 53 files changed, 9563 insertions(+), 787 deletions(-) create mode 100644 build/adr/custodian-agent-runtime/v1/index.html create mode 100644 build/adr/custodian-agent-runtime/v1/revisions/accepted-1/index.html create mode 100644 build/adr/custodian-canon-federation/v1/index.html create mode 100644 build/adr/custodian-canon-federation/v1/revisions/accepted-1/index.html create mode 100644 build/adr/custodian-connectivity-first/v1/index.html create mode 100644 build/adr/custodian-connectivity-first/v1/revisions/accepted-1/index.html create mode 100644 build/adr/custodian-cross-repo-workplans/v1/index.html create mode 100644 build/adr/custodian-cross-repo-workplans/v1/revisions/accepted-1/index.html create mode 100644 build/adr/custodian-federated-namespaces/v1/index.html create mode 100644 build/adr/custodian-federated-namespaces/v1/revisions/draft-2/index.html create mode 100644 build/adr/custodian-hub-authority/v1/index.html create mode 100644 build/adr/custodian-hub-authority/v1/revisions/draft-1/index.html create mode 100644 build/adr/custodian-materialized-derived-state/v1/index.html create mode 100644 build/adr/custodian-materialized-derived-state/v1/revisions/accepted-1/index.html create mode 100644 build/adr/custodian-workplan-identity/v1/index.html create mode 100644 build/adr/custodian-workplan-identity/v1/revisions/accepted-1/index.html create mode 100644 build/adr/custodian-workplans-as-repo-artefacts/v1/index.html create mode 100644 build/adr/custodian-workplans-as-repo-artefacts/v1/revisions/accepted-1/index.html create mode 100644 build/adr/railiance-decisions-live-in-the-repo/v1/index.html create mode 100644 build/adr/railiance-decisions-live-in-the-repo/v1/revisions/1.0/index.html create mode 100644 build/adr/railiance-placement-policy-ownership/v1/index.html create mode 100644 build/adr/railiance-placement-policy-ownership/v1/revisions/1.0/index.html create mode 100644 build/adr/railiance-s3-platform-service-boundary/v1/index.html create mode 100644 build/adr/railiance-s3-platform-service-boundary/v1/revisions/1.0/index.html create mode 100644 build/architecture/coulomb-estate/v0.1/revisions/draft-2/index.html create mode 100644 build/architecture/net-kingdom/v0.1/revisions/draft-2/index.html create mode 100644 build/architecture/railiance/v0.1/revisions/draft-2/index.html create mode 100644 build/architecture/state-hub/v0.1/revisions/draft-2/index.html create mode 100644 build/standards/iam-profile/v0.3/index.html create mode 100644 build/standards/iam-profile/v0.3/revisions/0.3/index.html diff --git a/build/adr/addressing-and-permanence/v1/index.html b/build/adr/addressing-and-permanence/v1/index.html index aeba0a7..6e0124c 100644 --- a/build/adr/addressing-and-permanence/v1/index.html +++ b/build/adr/addressing-and-permanence/v1/index.html @@ -1,6 +1,6 @@ - + Policy addressing and permanence -
policy-nexus-adr-0001 accepted · accepted-1 the-custodian reviewed 2026-08-18generated from canonical source — do not edit

Policy addressing and permanence

Source: policy-nexus · docs/adr/ADR-0001-addressing-and-permanence.md · 64b47d73b9fdf33df535db42c80db3a7435da5cf

Review due: 2027-02-18

  • Status: accepted
  • Date: 2026-08-18
  • Owner: the-custodian
+
policy-nexus-adr-0001 accepted · accepted-1 the-custodian reviewed 2026-08-18generated from canonical source — do not edit

Policy addressing and permanence

Source: policy-nexus · docs/adr/ADR-0001-addressing-and-permanence.md · 5cb88edf4d52a65ea31b1f2f53bcf6f71769d234

Review due: 2027-02-18

  • Status: accepted
  • Date: 2026-08-18
  • Owner: the-custodian

Decision

A document has one stable current address and immutable revision addresses:

/<kind>/<document>/<version>/
@@ -211,4 +211,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

Consequences

  • Builds fail if a source disappears, an id differs, a path collides, or an immutable revision would change; stale output is not silently called fresh.
  • Pages show status, revision, owner, last review and exact source revision.
  • Availability remains restart recovery on the single-node rail. This contract promises stable addressing, not a high-availability SLA.
-
policy-nexus-adr-0001 · accepted-1 · acceptedpolicy-nexus · docs/adr/ADR-0001-addressing-and-permanence.md · 64b47d73b9fdf33df535db42c80db3a7435da5cf
+
policy-nexus-adr-0001 · accepted-1 · acceptedpolicy-nexus · docs/adr/ADR-0001-addressing-and-permanence.md · 5cb88edf4d52a65ea31b1f2f53bcf6f71769d234
diff --git a/build/adr/custodian-agent-runtime/v1/index.html b/build/adr/custodian-agent-runtime/v1/index.html new file mode 100644 index 0000000..029635b --- /dev/null +++ b/build/adr/custodian-agent-runtime/v1/index.html @@ -0,0 +1,242 @@ + + + + +Custodian Agent Runtime — v0.1 Bootstrap Design + +
CUST-ADR-002 accepted · accepted-1 the-custodian reviewed 2026-03-12generated from canonical source — do not edit

Custodian Agent Runtime — v0.1 Bootstrap Design

Source: the-custodian · canon/architecture/adr-002-custodian-agent-runtime-design.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb

Review due: 2026-09-12

Status

+

Accepted.

+
+

Context

+

CUST-WP-0001 requires a first working skeleton of the Custodian as an acting agent: a loop that observes project state, reasons about it, and executes bounded write operations — without human interaction for each step.

+

The dependencies (llm-connect, operational Railiance infra) are now resolved. This ADR captures the five key architectural decisions for the v0.1 bootstrap.

+
+

Decisions

+

D1 — Location: runtime/ inside the-custodian (not a new repo)

+

Decision: The runtime lives under the-custodian/runtime/ as a standalone Python package (pyproject.toml, own venv) rather than a new repository.

+

Rationale: The runtime is tightly coupled to canon (reads constitution, memory) and the state-hub (its primary coordination layer). A separate repo adds friction with no v0.1 benefit. The existing runtime/ scaffold confirms the original intent. Extraction to its own repo is deferred to when the runtime has stable boundaries and multiple consumers.

+

D2 — OODA loop: single-pass synchronous CLI

+

Decision: One run() call = one complete Observe → Orient → Decide → Act cycle. Entry point is a CLI (agent.py) invoked manually or by a cron job.

+
Observe  — HTTP GET to state-hub: state summary or domain summary
+Orient   — Load constitution + build structured LLM context prompt
+Decide   — Single LLM call (via llm-connect) returns a JSON action plan
+Act      — Execute only sanctioned write operations from the plan
+

Rationale: Async event loops and daemons add operational complexity that v0.1 doesn't need. A single-pass CLI is testable, debuggable, and can be scheduled externally. The transition to an event-driven loop is Phase 2.

+

D3 — LLM backend: ClaudeCodeAdapter by default

+

Decision: The runtime uses llm_connect.ClaudeCodeAdapter as its default LLM backend (shells out to claude --print). Provider is configurable via --llm flag to support gemini, openrouter, or openai.

+

Rationale: ClaudeCodeAdapter requires no API key and honours the Local-First value (V2). All current deployments have Claude Code available. The llm-connect abstraction means switching providers is a one-line change.

+

D4 — Action constraint: three sanctioned write operations only

+

Decision: The agent may execute exactly three state-hub write operations without human approval:

+
  1. add_progress_event — append an observation to the event log
  2. update_task_status — mark a task done/in_progress (reversible)
  3. flag_for_human — raise an intervention flag (escalation, not action)
+

All other operations (create workstream, record decision, resolve decision, write to canon) require human approval before execution.

+

Rationale: Constitution §3/§4 require bounded agency. The three operations are either append-only (progress events), reversible (task status), or explicitly escalating (flag). They cannot produce irreversible harm.

+

D5 — LLM response format: JSON block in markdown

+

Decision: The LLM is prompted to return a Markdown response with a fenced ```json block containing the structured action plan:

+
{
+  "observations": ["..."],
+  "progress_events": [
+    {"summary": "...", "workstream_id": "...", "event_type": "note"}
+  ],
+  "tasks_to_update": [
+    {"task_id": "...", "status": "done"}
+  ],
+  "tasks_to_flag": [
+    {"task_id": "...", "note": "..."}
+  ]
+}
+

The surrounding Markdown is preserved as a human-readable reasoning trace and written to memory/working/ as a session note.

+

Rationale: JSON blocks are robust to extraction (delimited), LLMs produce them reliably with clear instructions, and the surrounding prose gives Bernd an auditable reasoning trace without requiring a separate reasoning step.

+
+

Consequences

+
  • runtime/ becomes a standalone Python package; make agent-run DOMAIN=x invokes it.
  • The runtime has no DB schema changes and no new API endpoints — it is a pure client of the existing state-hub HTTP API.
  • Autonomous actions are limited to append-only writes and escalations. Any expansion of the action surface requires a new ADR and human approval.
  • The v0.1 loop is single-user (Bernd). Multi-agent expansion is Phase 2+.
+
+

Deferred

+
  • Async event loop / daemon mode (Phase 2)
  • RAG over canon (Phase 1 roadmap item)
  • Tool adapters beyond state-hub HTTP (planned in runtime/tool_adapters/)
  • Deployment on Railiance k3s as a scheduled CronJob
+
CUST-ADR-002 · accepted-1 · acceptedthe-custodian · canon/architecture/adr-002-custodian-agent-runtime-design.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb
diff --git a/build/adr/custodian-agent-runtime/v1/revisions/accepted-1/index.html b/build/adr/custodian-agent-runtime/v1/revisions/accepted-1/index.html new file mode 100644 index 0000000..029635b --- /dev/null +++ b/build/adr/custodian-agent-runtime/v1/revisions/accepted-1/index.html @@ -0,0 +1,242 @@ + + + + +Custodian Agent Runtime — v0.1 Bootstrap Design + +
CUST-ADR-002 accepted · accepted-1 the-custodian reviewed 2026-03-12generated from canonical source — do not edit

Custodian Agent Runtime — v0.1 Bootstrap Design

Source: the-custodian · canon/architecture/adr-002-custodian-agent-runtime-design.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb

Review due: 2026-09-12

Status

+

Accepted.

+
+

Context

+

CUST-WP-0001 requires a first working skeleton of the Custodian as an acting agent: a loop that observes project state, reasons about it, and executes bounded write operations — without human interaction for each step.

+

The dependencies (llm-connect, operational Railiance infra) are now resolved. This ADR captures the five key architectural decisions for the v0.1 bootstrap.

+
+

Decisions

+

D1 — Location: runtime/ inside the-custodian (not a new repo)

+

Decision: The runtime lives under the-custodian/runtime/ as a standalone Python package (pyproject.toml, own venv) rather than a new repository.

+

Rationale: The runtime is tightly coupled to canon (reads constitution, memory) and the state-hub (its primary coordination layer). A separate repo adds friction with no v0.1 benefit. The existing runtime/ scaffold confirms the original intent. Extraction to its own repo is deferred to when the runtime has stable boundaries and multiple consumers.

+

D2 — OODA loop: single-pass synchronous CLI

+

Decision: One run() call = one complete Observe → Orient → Decide → Act cycle. Entry point is a CLI (agent.py) invoked manually or by a cron job.

+
Observe  — HTTP GET to state-hub: state summary or domain summary
+Orient   — Load constitution + build structured LLM context prompt
+Decide   — Single LLM call (via llm-connect) returns a JSON action plan
+Act      — Execute only sanctioned write operations from the plan
+

Rationale: Async event loops and daemons add operational complexity that v0.1 doesn't need. A single-pass CLI is testable, debuggable, and can be scheduled externally. The transition to an event-driven loop is Phase 2.

+

D3 — LLM backend: ClaudeCodeAdapter by default

+

Decision: The runtime uses llm_connect.ClaudeCodeAdapter as its default LLM backend (shells out to claude --print). Provider is configurable via --llm flag to support gemini, openrouter, or openai.

+

Rationale: ClaudeCodeAdapter requires no API key and honours the Local-First value (V2). All current deployments have Claude Code available. The llm-connect abstraction means switching providers is a one-line change.

+

D4 — Action constraint: three sanctioned write operations only

+

Decision: The agent may execute exactly three state-hub write operations without human approval:

+
  1. add_progress_event — append an observation to the event log
  2. update_task_status — mark a task done/in_progress (reversible)
  3. flag_for_human — raise an intervention flag (escalation, not action)
+

All other operations (create workstream, record decision, resolve decision, write to canon) require human approval before execution.

+

Rationale: Constitution §3/§4 require bounded agency. The three operations are either append-only (progress events), reversible (task status), or explicitly escalating (flag). They cannot produce irreversible harm.

+

D5 — LLM response format: JSON block in markdown

+

Decision: The LLM is prompted to return a Markdown response with a fenced ```json block containing the structured action plan:

+
{
+  "observations": ["..."],
+  "progress_events": [
+    {"summary": "...", "workstream_id": "...", "event_type": "note"}
+  ],
+  "tasks_to_update": [
+    {"task_id": "...", "status": "done"}
+  ],
+  "tasks_to_flag": [
+    {"task_id": "...", "note": "..."}
+  ]
+}
+

The surrounding Markdown is preserved as a human-readable reasoning trace and written to memory/working/ as a session note.

+

Rationale: JSON blocks are robust to extraction (delimited), LLMs produce them reliably with clear instructions, and the surrounding prose gives Bernd an auditable reasoning trace without requiring a separate reasoning step.

+
+

Consequences

+
  • runtime/ becomes a standalone Python package; make agent-run DOMAIN=x invokes it.
  • The runtime has no DB schema changes and no new API endpoints — it is a pure client of the existing state-hub HTTP API.
  • Autonomous actions are limited to append-only writes and escalations. Any expansion of the action surface requires a new ADR and human approval.
  • The v0.1 loop is single-user (Bernd). Multi-agent expansion is Phase 2+.
+
+

Deferred

+
  • Async event loop / daemon mode (Phase 2)
  • RAG over canon (Phase 1 roadmap item)
  • Tool adapters beyond state-hub HTTP (planned in runtime/tool_adapters/)
  • Deployment on Railiance k3s as a scheduled CronJob
+
CUST-ADR-002 · accepted-1 · acceptedthe-custodian · canon/architecture/adr-002-custodian-agent-runtime-design.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb
diff --git a/build/adr/custodian-canon-federation/v1/index.html b/build/adr/custodian-canon-federation/v1/index.html new file mode 100644 index 0000000..3d013bf --- /dev/null +++ b/build/adr/custodian-canon-federation/v1/index.html @@ -0,0 +1,253 @@ + + + + +Canon Federation and Concept Ownership Across InfoTech and Commerce + +
CUST-ADR-006 accepted · accepted-1 the-custodian reviewed 2026-08-17generated from canonical source — do not edit

Canon Federation and Concept Ownership Across InfoTech and Commerce

Source: the-custodian · canon/architecture/adr-006-canon-federation-concept-ownership.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb

Review due: 2027-02-17

Status

+

Accepted 2026-08-17. All seven ownership questions are resolved (see Resolutions); content may now move under CFED-WP-0001.

+
+

Context

+

The ecosystem currently runs two independent canons in the same market domain (infotech), with no cross-reference in either direction:

+
  • info-tech-canon — InfoTechCanon, v0.6.0, status service-baseline. Kernel + 12 models + 3 standards, with declared concept ownership per model, an orthogonality rule ("standards can import but not redefine each other"), and a live CLI/JSON/API surface built on infospace-bench.
  • identity-canon — documentation-only research repo, category research. Three IDENTITY-WP-* workplans, all finished; no active work since the commercial-identity research pass. ~60 concepts in canon/CanonicalGlossary.md.
+

Two problems follow.

+

Concept-ownership collision. InfoTechCanonOrganizationModel (:55) declares ownership of Actor, Person, Organization, OrganizationalUnit, Team, Group, Role, Position, Membership, Assignment, Responsibility, Authority, Accountability. InfoTechCanonAccessControlModel (:106) declares Subject, Principal, AccessRole, Permission, .... identity-canon independently defines Actor, Natural Person, Collective Actor, Organization, Group, Role, Membership Relationship, Authenticated Subject, Authorization Principal. Two canons claim the same concepts — exactly what InfoTechCanon's orthogonality rule exists to prevent.

+

An unowned gap. InfoTechCanonAccessControlModel (:214, "Boundary with Identity and Authentication") explicitly pushes identity provisioning, authentication factors, identity proofing, and account lifecycle out of scope, and :41 does the same for generic organization modelling. So Account, Identity Record, Identifier, Credential, Claim, Persona, Tenant, Realm, Synonymity Assertion, Assurance Level belong to no model at all.

+

Business semantics are accumulating in the wrong places. Roughly a third of identity-canon's glossary is not identity but counterparty/commercial modelling (Legal Entity, Beneficial Owner, Customer, Vendor, Commercial Commitment, Payment Mandate, Pipeline Pursuit, Counterparty Assurance Gradient, ...) — hence the repo's government secondary domain. Independently, info-tech-canon/demand/CapabilityProvisionEconomics.md (status accepted, 2026-08-15) records procurement and economics demand arriving in ITC-CAP from consumer resource-control, domain financials. Two unrelated donors pushing commercial semantics into technical canon is a domain boundary, not a coincidence. InfoTechCanon's own Purpose/Demand extension names this ScopePressure.

+
+

Decision

+

1. Three canons, federated by declared ownership.

+
CanonOwnsRepo
Custodian canonecosystem-normative governance: constitution, values, standards, ADRs, chartersthe-custodian/canon/
InfoTechCanonsemantics of information-processing systemsinfo-tech-canon
CommerceCanoncounterparty and commercial-relationship semanticscommerce-canon
+

Canons import but do not redefine each other's concepts, applying InfoTechCanon's existing orthogonality rule one level up.

+

2. identity-canon is renamed to commerce-canon, in place. Git history, State Hub registration, .repo-classification.yaml, and the finished IDENTITY-WP-* workplans are retained as provenance for the commercial content that stays. Identity content emigrates; nothing is archived. Structure follows info-tech-canon (canon.yaml, infospace/ with kernel/models/standards, assimilation/, mappings/, profiles/) per InfoTechCanonRepositoryLayoutStandard.

+

3. Identity becomes an InfoTechCanon model, at infospace/models/identity/InfoTechCanonIdentityModel.md (itc-ident), importing rather than redefining upstream concepts. This fills the gap InfoTechCanonAccessControlModel:214 leaves open.

+

4. Concept ownership is assigned as follows.

+

Imported by itc-ident, owned by itc-org: Actor · Natural Person → Person · Artificial Agent → Agent · Organization · Group · Role · Membership Relationship → Membership

+

Imported by itc-ident, owned by itc-access: Authenticated Subject → Subject · Authorization Principal → Principal

+

This follows identity-canon's own design principles: P1 makes Actor the participation root (owned upstream by itc-org), and P6 "Keep Authorization Projections Separate" already treats subject/principal as projections rather than identity-owned definitions.

+

Owned by itc-ident (new): Account · Service Account · Identity Record · Identifier · Scoped Identifier · Pseudonymous Identifier · Credential · Claim · Profile · Persona · Tenant · Realm · Synonymity Assertion · Lifecycle State · the actor-linking relationship taxonomy (Relationship, Affiliation, Following, Representation, Delegation, Administration, Trust) · convenience terms User, Subscriber

+

Owned by commerce-canon: Legal Entity · Legal Person · Beneficial Owner · Beneficial Ownership Relationship · Beneficial Ownership Exemption · Customer · Vendor · Commercial Relationship · Commercial Commitment · Payment Instrument Reference · Payment Mandate · Pipeline Pursuit · Commercial Record · Counterparty Assurance Gradient · Reputation Signal · Performance Evidence · Registry Identifier · Proxy Commercial Identifier · convenience terms Reputation, Customer Account

+

Owned by itc-evid, the evidence model (see R3, R5, R7): Evidence · Evidence Source · Adjudication Outcome

+

Identifier subtypes demonstrate the intended pattern: itc-ident owns Identifier; commerce-canon owns Registry Identifier and Proxy Commercial Identifier as specializations of it.

+

5. CommerceCanon grows by demand signal, not speculative authoring. New content enters through the mechanism InfoTechCanon already runs — a demand signal with named consumer evidence (see demand/). Plausible future consumers (fin-hub, target-revenue, adaptive-pricing, qonto-assistant) must pull; the canon does not push.

+

6. The Federated Organization Standard stays in Custodian canon. canon/standards/federated-organization-standard_v1.0.md is ecosystem-normative organizational architecture, human-gated — not commercial vocabulary. If it ever moves, it becomes an InfoTechCanon organization standard, not a CommerceCanon one.

+
+

Resolutions

+

The six collisions listed at draft time, resolved 2026-08-17. Two were settled by evidence already present in the models rather than by argument.

+

R1 — Scope: owned by itc-ident. There is no head-on collision: itc-access owns ResourceScope (:717, "the boundary within which access applies"), a narrower concept, not a general Scope. itc-ident owns the general concept, keeping it with Tenant and Realm — Tenant is defined as "an administrative or isolation scope", so separating it from its genus would split a definition from the concept it depends on. itc-access keeps ResourceScope as a refinement.

+

If landscape or information-space later need general scoping, promote Scope to the kernel on that demand signal, not pre-emptively.

+

R2 — Assurance Level: owned by itc-ident, distinct from governance assurance. A false collision. itc-gov owns AssuranceCase (:1178, a structured argument that a claim is justified) and AssuranceConclusion (:1184). identity's Assurance Level is NIST SP 800-63-4 IAL/AAL/FAL — graded confidence metadata on credentials, bindings, and federation assertions. They share an English word and nothing else. Both models carry a disambiguation note, because the word will keep causing this.

+

Design principle P12 ("Distinguish Assurance Dimensions") carries over: IAL, AAL, and FAL must not be collapsed into a single "trust level" on an account.

+

R3 — Evidence and Evidence Source are a general pair, owned together, and not by commerce. They are not competing definitions of one concept:

+
  • Evidence Source — an addressable information container: a document, file, or other artifact identifiable by URI.
  • Evidence — a distinct information item, textual or descriptive, drawn from a source: a quotation, an extracted value, a specific assertion.
+

Both may carry commentary. Which evidence is captured from a source depends on the interest being served.

+

Worked example: an invoice PDF is an Evidence Source; the amount, the issuer, and the due date are separate Evidence items within it. The common electronic- invoicing pattern of an XML embedding inside a signed PDF is exactly this structure — evidence pre-extracted and bound to its source so the extraction is itself tamper-evident.

+

The pair is domain-neutral (it extends to criminal, regulatory, and scientific evidence). Commerce, identity, and governance all use it; none owns it. Consequently itc-gov no longer owns Evidence; it imports it.

+

R4 — Relationship Tuple: owned by itc-access. Already modelled there (:549, under PolicyEvaluationEntity beside AuthorizationRequest, AuthorizationDecision, DecisionReason, EvaluationContext). identity-canon's own entry agrees: "Relationship tuples are not canonical identity roots. They project from actors, accounts, memberships, and delegations into authorization domains." itc-ident must not define it.

+

R5 — Adjudication Outcome: follows R3, owned with the evidence pair. Not itc-access AuthorizationDecision (a PDP allow/deny, :907) and not itc-gov Decision (a governance choice point). The concept is general rather than commercial: an arbitration award, court judgment, or regulatory consent order is evidence in employment, licensing, or compliance disputes as much as in commercial ones. Commerce is a consumer, not the owner.

+

Structurally it is Evidence — the outcome asserted — sourced from an Evidence Source such as the judgment document.

+

The assurance_tier dimension splits accordingly: the evidence model owns a general evidence-strength dimension; commerce-canon owns the Counterparty Assurance Gradient as its named four-tier application of it.

+

R6 — Community and Household extend itc-org; Family is a separate concept area. identity-canon defines "Family Or Household" as one entry. That conflation is rejected.

+

Community and Household are collective actors and slot under itc-org's existing CollectiveActor (:363, beside Person, HumanActor, NonHumanActor), honouring P4 ("Model Collective Actors Without Collapsing Them").

+

Family does not. Family carries substantial structure — kinship, guardianship, dependency, care, and legal, biological, and social parenthood — which changes over time and is subject to interpretation. Modelling it as one more collective actor is the specific mistake most family-oriented software makes, and it is why such software generally models families badly. It gets its own concept area.

+

Scope discipline applies: the family area is seeded, not authored. Record the concept, the privacy sensitivity already flagged in identity-canon ("may have legal implications outside the canon's scope"), and the open modelling questions. Do not build it out inside CFED-WP-0001; it grows on demand signal like any other canon content.

+

R7 — the evidence pair lives in a dedicated model, itc-evid. A new InfoTechCanon model at infospace/models/evidence/ owns Evidence, Evidence Source, Adjudication Outcome, and the general evidence-strength dimension.

+

itc-gov, itc-ident, and commerce-canon import it. Three named consumers existed before the model did, which is the demand signal the canon requires.

+

Rejected alternative: leaving both with itc-gov as incumbent owner of Evidence. That is cheaper and preserves the locality of the Policy-Control-Evidence chain pattern (:1391), but it would force identity and commerce to import "governance" in order to describe an invoice line item — mis-signalling evidence as a governance sub-topic when it is domain-neutral.

+

itc-gov retains AssuranceCase, AssuranceConclusion, Audit, and the Policy-Control-Evidence pattern, now expressed over imported evidence concepts.

+
+

Consequences

+

Positive. Every concept gains exactly one owner. The identity gap that itc-access explicitly declines is filled. Commercial semantics get a home before they accrete further into technical canon. A dormant research repo with no inbound references becomes a canon with declared consumers. A second canon tests whether InfoTechCanonRepositoryLayoutStandard is a real standard or merely InfoTechCanon's own shape described back to itself.

+

Negative. This is a concept-ownership reconciliation, not a file move: the first ~15 glossary entries must be rewritten as imports. Three canons cost more coordination than one. The identity-canon name disappears from tooling, bookmarks, and any external reference.

+

Risks. CommerceCanon could repeat identity-canon's failure mode — dormant, zero consumers, drifting — if it launches as a scaffold. Mitigated by decision 2 (it opens holding real, research-backed content) and decision 5 (growth requires consumer evidence).

+
+

References

+
  • ADR-001 — workplans originate as repo files; hub is a read model
  • ADR-005 — cross-repo workplans live in dedicated project repos
  • info-tech-canon/infospace/models/organization/InfoTechCanonOrganizationModel.md:55
  • info-tech-canon/infospace/models/access-control/InfoTechCanonAccessControlModel.md:106, :214
  • info-tech-canon/infospace/models/governance/InfoTechCanonGovernanceModel.md:107
  • info-tech-canon/demand/CapabilityProvisionEconomics.md
  • identity-canon/canon/CanonicalGlossary.md, canon/DesignPrinciples.md
+
CUST-ADR-006 · accepted-1 · acceptedthe-custodian · canon/architecture/adr-006-canon-federation-concept-ownership.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb
diff --git a/build/adr/custodian-canon-federation/v1/revisions/accepted-1/index.html b/build/adr/custodian-canon-federation/v1/revisions/accepted-1/index.html new file mode 100644 index 0000000..3d013bf --- /dev/null +++ b/build/adr/custodian-canon-federation/v1/revisions/accepted-1/index.html @@ -0,0 +1,253 @@ + + + + +Canon Federation and Concept Ownership Across InfoTech and Commerce + +
CUST-ADR-006 accepted · accepted-1 the-custodian reviewed 2026-08-17generated from canonical source — do not edit

Canon Federation and Concept Ownership Across InfoTech and Commerce

Source: the-custodian · canon/architecture/adr-006-canon-federation-concept-ownership.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb

Review due: 2027-02-17

Status

+

Accepted 2026-08-17. All seven ownership questions are resolved (see Resolutions); content may now move under CFED-WP-0001.

+
+

Context

+

The ecosystem currently runs two independent canons in the same market domain (infotech), with no cross-reference in either direction:

+
  • info-tech-canon — InfoTechCanon, v0.6.0, status service-baseline. Kernel + 12 models + 3 standards, with declared concept ownership per model, an orthogonality rule ("standards can import but not redefine each other"), and a live CLI/JSON/API surface built on infospace-bench.
  • identity-canon — documentation-only research repo, category research. Three IDENTITY-WP-* workplans, all finished; no active work since the commercial-identity research pass. ~60 concepts in canon/CanonicalGlossary.md.
+

Two problems follow.

+

Concept-ownership collision. InfoTechCanonOrganizationModel (:55) declares ownership of Actor, Person, Organization, OrganizationalUnit, Team, Group, Role, Position, Membership, Assignment, Responsibility, Authority, Accountability. InfoTechCanonAccessControlModel (:106) declares Subject, Principal, AccessRole, Permission, .... identity-canon independently defines Actor, Natural Person, Collective Actor, Organization, Group, Role, Membership Relationship, Authenticated Subject, Authorization Principal. Two canons claim the same concepts — exactly what InfoTechCanon's orthogonality rule exists to prevent.

+

An unowned gap. InfoTechCanonAccessControlModel (:214, "Boundary with Identity and Authentication") explicitly pushes identity provisioning, authentication factors, identity proofing, and account lifecycle out of scope, and :41 does the same for generic organization modelling. So Account, Identity Record, Identifier, Credential, Claim, Persona, Tenant, Realm, Synonymity Assertion, Assurance Level belong to no model at all.

+

Business semantics are accumulating in the wrong places. Roughly a third of identity-canon's glossary is not identity but counterparty/commercial modelling (Legal Entity, Beneficial Owner, Customer, Vendor, Commercial Commitment, Payment Mandate, Pipeline Pursuit, Counterparty Assurance Gradient, ...) — hence the repo's government secondary domain. Independently, info-tech-canon/demand/CapabilityProvisionEconomics.md (status accepted, 2026-08-15) records procurement and economics demand arriving in ITC-CAP from consumer resource-control, domain financials. Two unrelated donors pushing commercial semantics into technical canon is a domain boundary, not a coincidence. InfoTechCanon's own Purpose/Demand extension names this ScopePressure.

+
+

Decision

+

1. Three canons, federated by declared ownership.

+
CanonOwnsRepo
Custodian canonecosystem-normative governance: constitution, values, standards, ADRs, chartersthe-custodian/canon/
InfoTechCanonsemantics of information-processing systemsinfo-tech-canon
CommerceCanoncounterparty and commercial-relationship semanticscommerce-canon
+

Canons import but do not redefine each other's concepts, applying InfoTechCanon's existing orthogonality rule one level up.

+

2. identity-canon is renamed to commerce-canon, in place. Git history, State Hub registration, .repo-classification.yaml, and the finished IDENTITY-WP-* workplans are retained as provenance for the commercial content that stays. Identity content emigrates; nothing is archived. Structure follows info-tech-canon (canon.yaml, infospace/ with kernel/models/standards, assimilation/, mappings/, profiles/) per InfoTechCanonRepositoryLayoutStandard.

+

3. Identity becomes an InfoTechCanon model, at infospace/models/identity/InfoTechCanonIdentityModel.md (itc-ident), importing rather than redefining upstream concepts. This fills the gap InfoTechCanonAccessControlModel:214 leaves open.

+

4. Concept ownership is assigned as follows.

+

Imported by itc-ident, owned by itc-org: Actor · Natural Person → Person · Artificial Agent → Agent · Organization · Group · Role · Membership Relationship → Membership

+

Imported by itc-ident, owned by itc-access: Authenticated Subject → Subject · Authorization Principal → Principal

+

This follows identity-canon's own design principles: P1 makes Actor the participation root (owned upstream by itc-org), and P6 "Keep Authorization Projections Separate" already treats subject/principal as projections rather than identity-owned definitions.

+

Owned by itc-ident (new): Account · Service Account · Identity Record · Identifier · Scoped Identifier · Pseudonymous Identifier · Credential · Claim · Profile · Persona · Tenant · Realm · Synonymity Assertion · Lifecycle State · the actor-linking relationship taxonomy (Relationship, Affiliation, Following, Representation, Delegation, Administration, Trust) · convenience terms User, Subscriber

+

Owned by commerce-canon: Legal Entity · Legal Person · Beneficial Owner · Beneficial Ownership Relationship · Beneficial Ownership Exemption · Customer · Vendor · Commercial Relationship · Commercial Commitment · Payment Instrument Reference · Payment Mandate · Pipeline Pursuit · Commercial Record · Counterparty Assurance Gradient · Reputation Signal · Performance Evidence · Registry Identifier · Proxy Commercial Identifier · convenience terms Reputation, Customer Account

+

Owned by itc-evid, the evidence model (see R3, R5, R7): Evidence · Evidence Source · Adjudication Outcome

+

Identifier subtypes demonstrate the intended pattern: itc-ident owns Identifier; commerce-canon owns Registry Identifier and Proxy Commercial Identifier as specializations of it.

+

5. CommerceCanon grows by demand signal, not speculative authoring. New content enters through the mechanism InfoTechCanon already runs — a demand signal with named consumer evidence (see demand/). Plausible future consumers (fin-hub, target-revenue, adaptive-pricing, qonto-assistant) must pull; the canon does not push.

+

6. The Federated Organization Standard stays in Custodian canon. canon/standards/federated-organization-standard_v1.0.md is ecosystem-normative organizational architecture, human-gated — not commercial vocabulary. If it ever moves, it becomes an InfoTechCanon organization standard, not a CommerceCanon one.

+
+

Resolutions

+

The six collisions listed at draft time, resolved 2026-08-17. Two were settled by evidence already present in the models rather than by argument.

+

R1 — Scope: owned by itc-ident. There is no head-on collision: itc-access owns ResourceScope (:717, "the boundary within which access applies"), a narrower concept, not a general Scope. itc-ident owns the general concept, keeping it with Tenant and Realm — Tenant is defined as "an administrative or isolation scope", so separating it from its genus would split a definition from the concept it depends on. itc-access keeps ResourceScope as a refinement.

+

If landscape or information-space later need general scoping, promote Scope to the kernel on that demand signal, not pre-emptively.

+

R2 — Assurance Level: owned by itc-ident, distinct from governance assurance. A false collision. itc-gov owns AssuranceCase (:1178, a structured argument that a claim is justified) and AssuranceConclusion (:1184). identity's Assurance Level is NIST SP 800-63-4 IAL/AAL/FAL — graded confidence metadata on credentials, bindings, and federation assertions. They share an English word and nothing else. Both models carry a disambiguation note, because the word will keep causing this.

+

Design principle P12 ("Distinguish Assurance Dimensions") carries over: IAL, AAL, and FAL must not be collapsed into a single "trust level" on an account.

+

R3 — Evidence and Evidence Source are a general pair, owned together, and not by commerce. They are not competing definitions of one concept:

+
  • Evidence Source — an addressable information container: a document, file, or other artifact identifiable by URI.
  • Evidence — a distinct information item, textual or descriptive, drawn from a source: a quotation, an extracted value, a specific assertion.
+

Both may carry commentary. Which evidence is captured from a source depends on the interest being served.

+

Worked example: an invoice PDF is an Evidence Source; the amount, the issuer, and the due date are separate Evidence items within it. The common electronic- invoicing pattern of an XML embedding inside a signed PDF is exactly this structure — evidence pre-extracted and bound to its source so the extraction is itself tamper-evident.

+

The pair is domain-neutral (it extends to criminal, regulatory, and scientific evidence). Commerce, identity, and governance all use it; none owns it. Consequently itc-gov no longer owns Evidence; it imports it.

+

R4 — Relationship Tuple: owned by itc-access. Already modelled there (:549, under PolicyEvaluationEntity beside AuthorizationRequest, AuthorizationDecision, DecisionReason, EvaluationContext). identity-canon's own entry agrees: "Relationship tuples are not canonical identity roots. They project from actors, accounts, memberships, and delegations into authorization domains." itc-ident must not define it.

+

R5 — Adjudication Outcome: follows R3, owned with the evidence pair. Not itc-access AuthorizationDecision (a PDP allow/deny, :907) and not itc-gov Decision (a governance choice point). The concept is general rather than commercial: an arbitration award, court judgment, or regulatory consent order is evidence in employment, licensing, or compliance disputes as much as in commercial ones. Commerce is a consumer, not the owner.

+

Structurally it is Evidence — the outcome asserted — sourced from an Evidence Source such as the judgment document.

+

The assurance_tier dimension splits accordingly: the evidence model owns a general evidence-strength dimension; commerce-canon owns the Counterparty Assurance Gradient as its named four-tier application of it.

+

R6 — Community and Household extend itc-org; Family is a separate concept area. identity-canon defines "Family Or Household" as one entry. That conflation is rejected.

+

Community and Household are collective actors and slot under itc-org's existing CollectiveActor (:363, beside Person, HumanActor, NonHumanActor), honouring P4 ("Model Collective Actors Without Collapsing Them").

+

Family does not. Family carries substantial structure — kinship, guardianship, dependency, care, and legal, biological, and social parenthood — which changes over time and is subject to interpretation. Modelling it as one more collective actor is the specific mistake most family-oriented software makes, and it is why such software generally models families badly. It gets its own concept area.

+

Scope discipline applies: the family area is seeded, not authored. Record the concept, the privacy sensitivity already flagged in identity-canon ("may have legal implications outside the canon's scope"), and the open modelling questions. Do not build it out inside CFED-WP-0001; it grows on demand signal like any other canon content.

+

R7 — the evidence pair lives in a dedicated model, itc-evid. A new InfoTechCanon model at infospace/models/evidence/ owns Evidence, Evidence Source, Adjudication Outcome, and the general evidence-strength dimension.

+

itc-gov, itc-ident, and commerce-canon import it. Three named consumers existed before the model did, which is the demand signal the canon requires.

+

Rejected alternative: leaving both with itc-gov as incumbent owner of Evidence. That is cheaper and preserves the locality of the Policy-Control-Evidence chain pattern (:1391), but it would force identity and commerce to import "governance" in order to describe an invoice line item — mis-signalling evidence as a governance sub-topic when it is domain-neutral.

+

itc-gov retains AssuranceCase, AssuranceConclusion, Audit, and the Policy-Control-Evidence pattern, now expressed over imported evidence concepts.

+
+

Consequences

+

Positive. Every concept gains exactly one owner. The identity gap that itc-access explicitly declines is filled. Commercial semantics get a home before they accrete further into technical canon. A dormant research repo with no inbound references becomes a canon with declared consumers. A second canon tests whether InfoTechCanonRepositoryLayoutStandard is a real standard or merely InfoTechCanon's own shape described back to itself.

+

Negative. This is a concept-ownership reconciliation, not a file move: the first ~15 glossary entries must be rewritten as imports. Three canons cost more coordination than one. The identity-canon name disappears from tooling, bookmarks, and any external reference.

+

Risks. CommerceCanon could repeat identity-canon's failure mode — dormant, zero consumers, drifting — if it launches as a scaffold. Mitigated by decision 2 (it opens holding real, research-backed content) and decision 5 (growth requires consumer evidence).

+
+

References

+
  • ADR-001 — workplans originate as repo files; hub is a read model
  • ADR-005 — cross-repo workplans live in dedicated project repos
  • info-tech-canon/infospace/models/organization/InfoTechCanonOrganizationModel.md:55
  • info-tech-canon/infospace/models/access-control/InfoTechCanonAccessControlModel.md:106, :214
  • info-tech-canon/infospace/models/governance/InfoTechCanonGovernanceModel.md:107
  • info-tech-canon/demand/CapabilityProvisionEconomics.md
  • identity-canon/canon/CanonicalGlossary.md, canon/DesignPrinciples.md
+
CUST-ADR-006 · accepted-1 · acceptedthe-custodian · canon/architecture/adr-006-canon-federation-concept-ownership.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb
diff --git a/build/adr/custodian-connectivity-first/v1/index.html b/build/adr/custodian-connectivity-first/v1/index.html new file mode 100644 index 0000000..753df7a --- /dev/null +++ b/build/adr/custodian-connectivity-first/v1/index.html @@ -0,0 +1,236 @@ + + + + +Connectivity-First Network Posture for Custodian Infrastructure + +
CUST-ADR-004 accepted · accepted-1 the-custodian reviewed 2026-03-26generated from canonical source — do not edit

Connectivity-First Network Posture for Custodian Infrastructure

Source: the-custodian · canon/architecture/adr-004-connectivity-first-network-posture.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb

Review due: 2026-09-26

Status

+

Accepted.

+
+

Context

+

The Custodian infrastructure spans multiple machines: a primary workstation, a shared compute node (COULOMBCORE), and Railiance cluster nodes. Agents running on remote machines need to reach the state-hub API and MCP server, which live on the workstation. Human operators and agents also need to reach remote services (k3s API, Gitea, Temporal) from the workstation.

+

Two network postures were considered for how these components communicate:

+

Option A — Connectivity-first: Components are connected by default via controlled, observable access paths (reverse SSH tunnels managed by ops-bridge). Isolation is added selectively where there is a specific threat model or compliance reason to do so.

+

Option B — Isolation-first (zero-trust): No component trusts any other by default. Every connection requires mutual authentication, short-lived credentials, and explicit authorisation at the point of use. Connectivity is earned, not assumed.

+

This decision is architectural policy — it governs how ops-bridge tunnels are designed, how agent-to-hub communication works, and how new infrastructure components are onboarded.

+
+

Decision

+

Connectivity-first, with isolation as a deliberate option.

+

The default posture for Custodian infrastructure is: components that need to work together are connected. Access paths are explicit, observable, and managed (via ops-bridge), but they are persistent by default rather than ephemeral. Isolation is introduced where there is a specific, articulated reason — not as a blanket policy applied uniformly.

+
+

Rationale

+

1. Scale and team size

+

The infrastructure is operated by a single human and a bounded set of automation agents. The overhead of zero-trust (credential rotation, SPIFFE/SPIRE identity, mTLS everywhere, short-lived tokens per request) is disproportionate for this scale. It would consume significant operational complexity without a commensurate security return.

+

2. Observability over perimeter hardening

+

The primary security control at this scale is observability: knowing what connected, when, from where, and what it did. ops-bridge provides this — every tunnel is named, actor-attributed, health-checked, and audited. A perimeter of invisible short-lived connections would actually reduce observability.

+

3. The threat model does not require zero-trust today

+

The main threats are:

+
  • A runaway agent consuming resources (mitigated by nproc/memory cgroups)
  • A compromised workload reaching state-hub and corrupting state (mitigated by the read-model design of state-hub — write surface is narrow and sanctioned)
  • An external attacker reaching internal services (mitigated by the tunnels being reverse SSH — no inbound ports exposed)
+

Zero-trust would address a different threat model: lateral movement between hostile tenants, or untrusted code running in the same environment as sensitive data. That is not the current situation.

+

4. Degrade-gracefully requires persistent connectivity

+

The Custodian's foundational value of local-first, degrade-gracefully requires that agents can orient themselves even when some connections are slow or partially degraded. Ephemeral connectivity (zero-trust tokens, service mesh sidecars) introduces additional failure modes that conflict with graceful degradation. Persistent SSH tunnels with auto-reconnect are more resilient to intermittent conditions.

+

5. Isolation remains the right choice in specific cases

+

Connectivity-first does not mean no isolation. The following cases call for explicit isolation and are handled separately:

+
  • Tenant separation (when/if multi-user or multi-org) — each tenant gets its own network segment
  • Privileged execution — CI runners and agent actions with write access to production systems run in ephemeral, isolated environments (per the Privileged Execution Control standard)
  • Secrets — credentials are never transmitted over tunnels in plaintext; age-encrypted at rest, SOPS for config
+
+

Consequences

+

Immediate

+
  • ops-bridge tunnels are persistent (max_attempts: 0, auto-reconnect) and are treated as infrastructure, not one-off connections
  • Agents on remote machines check tunnel health at session start and restore dropped tunnels before accessing state-hub (documented in global CLAUDE.md)
  • New infrastructure components are onboarded with a named tunnel entry in ~/.config/bridge/tunnels.yaml — not ad-hoc SSH commands
+

Deferred

+
  • If the infrastructure grows to multi-tenant or multi-operator, this decision should be revisited. At that point, isolation-first becomes proportionate.
  • If a security audit identifies a specific lateral movement risk, targeted isolation (network policy, mTLS for that service) is the response — not a wholesale posture change.
+
+

Alternatives Rejected

+

Zero-trust / isolation-first

+

Rejected for current scale. The operational overhead (credential lifecycle, service mesh, mutual TLS) is disproportionate, observability would decrease, and the threat model does not require it. Noted for re-evaluation at multi- tenant scale.

+

VPN (WireGuard / Tailscale)

+

Considered briefly. VPN would solve the connectivity problem but introduces a persistent network layer that all traffic traverses, reducing the explicitness of individual access paths. ops-bridge tunnels are per-service and per-actor, which gives better observability and blast-radius control. VPN is not ruled out as a future complement but is not the primary approach.

+

Ad-hoc SSH (no ops-bridge)

+

The pre-ops-bridge approach. Rejected because it has no health checks, no actor attribution, no audit log, and requires manual intervention to restore. ops-bridge formalises the same SSH tunnel pattern with operational discipline.

+
CUST-ADR-004 · accepted-1 · acceptedthe-custodian · canon/architecture/adr-004-connectivity-first-network-posture.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb
diff --git a/build/adr/custodian-connectivity-first/v1/revisions/accepted-1/index.html b/build/adr/custodian-connectivity-first/v1/revisions/accepted-1/index.html new file mode 100644 index 0000000..753df7a --- /dev/null +++ b/build/adr/custodian-connectivity-first/v1/revisions/accepted-1/index.html @@ -0,0 +1,236 @@ + + + + +Connectivity-First Network Posture for Custodian Infrastructure + +
CUST-ADR-004 accepted · accepted-1 the-custodian reviewed 2026-03-26generated from canonical source — do not edit

Connectivity-First Network Posture for Custodian Infrastructure

Source: the-custodian · canon/architecture/adr-004-connectivity-first-network-posture.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb

Review due: 2026-09-26

Status

+

Accepted.

+
+

Context

+

The Custodian infrastructure spans multiple machines: a primary workstation, a shared compute node (COULOMBCORE), and Railiance cluster nodes. Agents running on remote machines need to reach the state-hub API and MCP server, which live on the workstation. Human operators and agents also need to reach remote services (k3s API, Gitea, Temporal) from the workstation.

+

Two network postures were considered for how these components communicate:

+

Option A — Connectivity-first: Components are connected by default via controlled, observable access paths (reverse SSH tunnels managed by ops-bridge). Isolation is added selectively where there is a specific threat model or compliance reason to do so.

+

Option B — Isolation-first (zero-trust): No component trusts any other by default. Every connection requires mutual authentication, short-lived credentials, and explicit authorisation at the point of use. Connectivity is earned, not assumed.

+

This decision is architectural policy — it governs how ops-bridge tunnels are designed, how agent-to-hub communication works, and how new infrastructure components are onboarded.

+
+

Decision

+

Connectivity-first, with isolation as a deliberate option.

+

The default posture for Custodian infrastructure is: components that need to work together are connected. Access paths are explicit, observable, and managed (via ops-bridge), but they are persistent by default rather than ephemeral. Isolation is introduced where there is a specific, articulated reason — not as a blanket policy applied uniformly.

+
+

Rationale

+

1. Scale and team size

+

The infrastructure is operated by a single human and a bounded set of automation agents. The overhead of zero-trust (credential rotation, SPIFFE/SPIRE identity, mTLS everywhere, short-lived tokens per request) is disproportionate for this scale. It would consume significant operational complexity without a commensurate security return.

+

2. Observability over perimeter hardening

+

The primary security control at this scale is observability: knowing what connected, when, from where, and what it did. ops-bridge provides this — every tunnel is named, actor-attributed, health-checked, and audited. A perimeter of invisible short-lived connections would actually reduce observability.

+

3. The threat model does not require zero-trust today

+

The main threats are:

+
  • A runaway agent consuming resources (mitigated by nproc/memory cgroups)
  • A compromised workload reaching state-hub and corrupting state (mitigated by the read-model design of state-hub — write surface is narrow and sanctioned)
  • An external attacker reaching internal services (mitigated by the tunnels being reverse SSH — no inbound ports exposed)
+

Zero-trust would address a different threat model: lateral movement between hostile tenants, or untrusted code running in the same environment as sensitive data. That is not the current situation.

+

4. Degrade-gracefully requires persistent connectivity

+

The Custodian's foundational value of local-first, degrade-gracefully requires that agents can orient themselves even when some connections are slow or partially degraded. Ephemeral connectivity (zero-trust tokens, service mesh sidecars) introduces additional failure modes that conflict with graceful degradation. Persistent SSH tunnels with auto-reconnect are more resilient to intermittent conditions.

+

5. Isolation remains the right choice in specific cases

+

Connectivity-first does not mean no isolation. The following cases call for explicit isolation and are handled separately:

+
  • Tenant separation (when/if multi-user or multi-org) — each tenant gets its own network segment
  • Privileged execution — CI runners and agent actions with write access to production systems run in ephemeral, isolated environments (per the Privileged Execution Control standard)
  • Secrets — credentials are never transmitted over tunnels in plaintext; age-encrypted at rest, SOPS for config
+
+

Consequences

+

Immediate

+
  • ops-bridge tunnels are persistent (max_attempts: 0, auto-reconnect) and are treated as infrastructure, not one-off connections
  • Agents on remote machines check tunnel health at session start and restore dropped tunnels before accessing state-hub (documented in global CLAUDE.md)
  • New infrastructure components are onboarded with a named tunnel entry in ~/.config/bridge/tunnels.yaml — not ad-hoc SSH commands
+

Deferred

+
  • If the infrastructure grows to multi-tenant or multi-operator, this decision should be revisited. At that point, isolation-first becomes proportionate.
  • If a security audit identifies a specific lateral movement risk, targeted isolation (network policy, mTLS for that service) is the response — not a wholesale posture change.
+
+

Alternatives Rejected

+

Zero-trust / isolation-first

+

Rejected for current scale. The operational overhead (credential lifecycle, service mesh, mutual TLS) is disproportionate, observability would decrease, and the threat model does not require it. Noted for re-evaluation at multi- tenant scale.

+

VPN (WireGuard / Tailscale)

+

Considered briefly. VPN would solve the connectivity problem but introduces a persistent network layer that all traffic traverses, reducing the explicitness of individual access paths. ops-bridge tunnels are per-service and per-actor, which gives better observability and blast-radius control. VPN is not ruled out as a future complement but is not the primary approach.

+

Ad-hoc SSH (no ops-bridge)

+

The pre-ops-bridge approach. Rejected because it has no health checks, no actor attribution, no audit log, and requires manual intervention to restore. ops-bridge formalises the same SSH tunnel pattern with operational discipline.

+
CUST-ADR-004 · accepted-1 · acceptedthe-custodian · canon/architecture/adr-004-connectivity-first-network-posture.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb
diff --git a/build/adr/custodian-cross-repo-workplans/v1/index.html b/build/adr/custodian-cross-repo-workplans/v1/index.html new file mode 100644 index 0000000..cb8edec --- /dev/null +++ b/build/adr/custodian-cross-repo-workplans/v1/index.html @@ -0,0 +1,225 @@ + + + + +Cross-Repo Workplans Live in Dedicated Project Repos + +
CUST-ADR-005 accepted · accepted-1 the-custodian reviewed 2026-06-22generated from canonical source — do not edit

Cross-Repo Workplans Live in Dedicated Project Repos

Source: the-custodian · canon/architecture/adr-005-cross-repo-workplans-project-repos.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb

Review due: 2026-12-22

Status

+

Accepted.

+
+

Context

+

ADR-001 established that workplans and work items originate as files in the repository that owns them, so the State Hub can rebuild its coordination state from repo-owned files alone. The repo-classification redesign (CUST-WP-0050) takes the next step: it makes the repo the primary anchor for a workplan (workstreams.repo_id becomes required) and derives the market-domain from the repo's .repo-classification.yaml rather than maintaining a separate topic/domain spine. Repos are the most stable, git-managed entities in the ecosystem; binding to them is the most durable anchor available.

+

This raises an unavoidable question: what anchors a genuinely cross-repo workplan? Some efforts coordinate change across many repositories — ecosystem migrations, the FOS hub bootstrap (CUST-WP-0025), or CUST-WP-0050 itself, which touches ~70 repos. If every workplan must bind to exactly one repo:

+
  • binding it to one arbitrary product repo misrepresents the work and pollutes that repo's history with coordination it does not own;
  • leaving it unbound reintroduces the hub-only orphan that ADR-001 forbids;
  • modelling it as an array of repo_ids breaks the "one stable anchor, clear ownership, clean lifecycle" property and complicates the rebuild principle.
+
+

Decision

+

**A complex cross-repo workplan gets its own dedicated project repo.**

+
  • The project repo is a real, git-managed repository. It owns the coordination workplan, its tasks, its decisions, and any cross-cutting artefacts. It is the required repo anchor for that workplan, satisfying the repo-primary-anchor rule without distorting any single product repo.
  • The project repo is classified under the Repo Classification Standard, normally category: project. Its domain/tags describe the effort, not any one product.
  • Implementation still happens in the product repos. Changes land via per-repo workplans and PRs in the repos being modified. The project repo coordinates and references that work (via dependency edges / links); it does not own product code.
  • On completion, the project repo is retired to archive — not deleted. Its durable results live on in the product repos it modified (the merged changes are the outcome). The archived project repo remains as an immutable provenance record of the coordination, consistent with the append-only-memory value.
+

The project repo's completion record MUST list the product repos it modified and link to the merged PRs/commits, so the trail survives archival.

+
+

Lifecycle

+
draft → active → completed → archived
+
  • active — work in progress; workplan status: active; repo live in Gitea and registered in the Hub.
  • completed — all tasks done; completion record written (modified repos + links).
  • archived — repo archived in Gitea and status: archived in the Hub. The workplan moves to workplans/archived/ per the workplan convention. Results persist in the product repos; the project repo is read-only history.
+
+

Naming

+

Project repos MUST use the prj-<kebab-slug> prefix.

+

Exact naming, required files (GOAL.md instead of durable-product INTENT.md), authority boundary, residual handoff, and archive procedure are defined in:

+

canon/standards/project-repository-flavor_v0.1.md

+

That standard closes the naming open question previously deferred to CUST-WP-0050 (D1a). The illustrative proj- form mentioned in earlier drafts is not used for new repositories.

+
+

Consequences

+
  • Pro: every workplan — including cross-repo ones — has a stable, git-managed anchor; no hub-only orphans; the rebuild principle (ADR-001) holds.
  • Pro: the classification standard applies uniformly; project repos are just repos with category: project.
  • Pro: clean, explicit lifecycle; results are never lost on retirement because they live in the modified product repos.
  • Con: proliferation of short-lived repos; requires discipline around the naming and archival convention.
  • Con: cross-references between the project repo and the product repos it modified must be recorded deliberately, or the provenance trail degrades after archival.
  • Con: judgement is required on when an effort is "complex enough" to merit a project repo versus a single-repo workplan; small cross-cutting changes should not spawn a repo.
+
+

Alternatives Considered

+
  • Bind to a "lead" product repo. Rejected: distorts that repo's history and creates ambiguous ownership.
  • Keep an optional hub-only topic for cross-repo coordination. Rejected: reintroduces the soft, non-git-managed spine that CUST-WP-0050 removes and ADR-001 discourages.
  • Multi-anchor workplan (array of repo_ids, no primary). Rejected: breaks single-anchor simplicity, ownership clarity, and lifecycle modelling.
+
+
CUST-ADR-005 · accepted-1 · acceptedthe-custodian · canon/architecture/adr-005-cross-repo-workplans-project-repos.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb
diff --git a/build/adr/custodian-cross-repo-workplans/v1/revisions/accepted-1/index.html b/build/adr/custodian-cross-repo-workplans/v1/revisions/accepted-1/index.html new file mode 100644 index 0000000..cb8edec --- /dev/null +++ b/build/adr/custodian-cross-repo-workplans/v1/revisions/accepted-1/index.html @@ -0,0 +1,225 @@ + + + + +Cross-Repo Workplans Live in Dedicated Project Repos + +
CUST-ADR-005 accepted · accepted-1 the-custodian reviewed 2026-06-22generated from canonical source — do not edit

Cross-Repo Workplans Live in Dedicated Project Repos

Source: the-custodian · canon/architecture/adr-005-cross-repo-workplans-project-repos.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb

Review due: 2026-12-22

Status

+

Accepted.

+
+

Context

+

ADR-001 established that workplans and work items originate as files in the repository that owns them, so the State Hub can rebuild its coordination state from repo-owned files alone. The repo-classification redesign (CUST-WP-0050) takes the next step: it makes the repo the primary anchor for a workplan (workstreams.repo_id becomes required) and derives the market-domain from the repo's .repo-classification.yaml rather than maintaining a separate topic/domain spine. Repos are the most stable, git-managed entities in the ecosystem; binding to them is the most durable anchor available.

+

This raises an unavoidable question: what anchors a genuinely cross-repo workplan? Some efforts coordinate change across many repositories — ecosystem migrations, the FOS hub bootstrap (CUST-WP-0025), or CUST-WP-0050 itself, which touches ~70 repos. If every workplan must bind to exactly one repo:

+
  • binding it to one arbitrary product repo misrepresents the work and pollutes that repo's history with coordination it does not own;
  • leaving it unbound reintroduces the hub-only orphan that ADR-001 forbids;
  • modelling it as an array of repo_ids breaks the "one stable anchor, clear ownership, clean lifecycle" property and complicates the rebuild principle.
+
+

Decision

+

**A complex cross-repo workplan gets its own dedicated project repo.**

+
  • The project repo is a real, git-managed repository. It owns the coordination workplan, its tasks, its decisions, and any cross-cutting artefacts. It is the required repo anchor for that workplan, satisfying the repo-primary-anchor rule without distorting any single product repo.
  • The project repo is classified under the Repo Classification Standard, normally category: project. Its domain/tags describe the effort, not any one product.
  • Implementation still happens in the product repos. Changes land via per-repo workplans and PRs in the repos being modified. The project repo coordinates and references that work (via dependency edges / links); it does not own product code.
  • On completion, the project repo is retired to archive — not deleted. Its durable results live on in the product repos it modified (the merged changes are the outcome). The archived project repo remains as an immutable provenance record of the coordination, consistent with the append-only-memory value.
+

The project repo's completion record MUST list the product repos it modified and link to the merged PRs/commits, so the trail survives archival.

+
+

Lifecycle

+
draft → active → completed → archived
+
  • active — work in progress; workplan status: active; repo live in Gitea and registered in the Hub.
  • completed — all tasks done; completion record written (modified repos + links).
  • archived — repo archived in Gitea and status: archived in the Hub. The workplan moves to workplans/archived/ per the workplan convention. Results persist in the product repos; the project repo is read-only history.
+
+

Naming

+

Project repos MUST use the prj-<kebab-slug> prefix.

+

Exact naming, required files (GOAL.md instead of durable-product INTENT.md), authority boundary, residual handoff, and archive procedure are defined in:

+

canon/standards/project-repository-flavor_v0.1.md

+

That standard closes the naming open question previously deferred to CUST-WP-0050 (D1a). The illustrative proj- form mentioned in earlier drafts is not used for new repositories.

+
+

Consequences

+
  • Pro: every workplan — including cross-repo ones — has a stable, git-managed anchor; no hub-only orphans; the rebuild principle (ADR-001) holds.
  • Pro: the classification standard applies uniformly; project repos are just repos with category: project.
  • Pro: clean, explicit lifecycle; results are never lost on retirement because they live in the modified product repos.
  • Con: proliferation of short-lived repos; requires discipline around the naming and archival convention.
  • Con: cross-references between the project repo and the product repos it modified must be recorded deliberately, or the provenance trail degrades after archival.
  • Con: judgement is required on when an effort is "complex enough" to merit a project repo versus a single-repo workplan; small cross-cutting changes should not spawn a repo.
+
+

Alternatives Considered

+
  • Bind to a "lead" product repo. Rejected: distorts that repo's history and creates ambiguous ownership.
  • Keep an optional hub-only topic for cross-repo coordination. Rejected: reintroduces the soft, non-git-managed spine that CUST-WP-0050 removes and ADR-001 discourages.
  • Multi-anchor workplan (array of repo_ids, no primary). Rejected: breaks single-anchor simplicity, ownership clarity, and lifecycle modelling.
+
+
CUST-ADR-005 · accepted-1 · acceptedthe-custodian · canon/architecture/adr-005-cross-repo-workplans-project-repos.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb
diff --git a/build/adr/custodian-federated-namespaces/v1/index.html b/build/adr/custodian-federated-namespaces/v1/index.html new file mode 100644 index 0000000..99baff5 --- /dev/null +++ b/build/adr/custodian-federated-namespaces/v1/index.html @@ -0,0 +1,284 @@ + + + + +Federated Namespaces + +
CUST-ADR-011 proposed · draft-2 the-custodian reviewed 2026-08-17generated from canonical source — do not edit

Federated Namespaces

Source: the-custodian · canon/architecture/adr-011-federated-namespaces-and-reconciliation-limits.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb

Review due: 2027-02-17

Status

+

Proposed, draft-2. Amends ADR-007 decisions 1 and 2; extends ADR-010 decision 4; adopts the plane/ladder/posture form and the accuracy-not-altitude conformance rule from ADR-008 (Multi-Tenancy Framework).

+
+

Context

+

The ecosystem must be federation-capable — able to work without a live link to central services — and chain-of-command efficient. federated-organization-standard_v1.0 already resolves the organizational half:

+

global coherence is achieved through policy, escalation, and shared protocols rather than through monolithic control (:51) bounded autonomy plus disciplined coordination (:86)

+

Authority is a policy layer; availability is a mechanism. Distributed version control makes the same separation: an integration branch is privileged by agreement, never by a technical property.

+

One accepted decision violates this. ADR-007 decision 1 requires running numbers that are globally unique and allocated forward only. Global sequential allocation requires a coordinator — precisely the central dependency federation must survive. Two disconnected forks each allocating RCLUSTER-WP-0015 is a certainty, not an edge case.

+

This is not hypothetical. Instance-per-client tenancy (CUST-WP-0058) already makes every client deployment a fork of the stack; the business model committed to forking before the identifier scheme could express it.

+

Why this draft changed form

+

Draft-1 stated federation as a set of binary rules — notably "records fork, effects do not". That is a single verdict where a graduated declaration belongs, and it is the same conflation ADR-008 §03 diagnoses for multi-tenancy: "'Is this multi-tenant?' is treated as one question. It is four, and they are independent."

+

"Is this federation-capable?" is likewise not one question. A namespace can be strong on identity and incapable of disconnected operation; it can operate disconnected and have no way to reconcile afterwards. Draft-1 could not say so.

+

This draft reuses ADR-008's vocabulary rather than inventing a parallel one. Two competing maturity vocabularies in one canon would be its own collision.

+
+

Decision

+

1. Records live in a namespace. A namespace is a federated branch of the ecosystem — a fleet instance, a client deployment, an autonomous domain that may operate disconnected. It is the unit of sovereignty in FOS terms and the unit of divergence here.

+

2. Federation is four orthogonal planes.

+
PlaneQuestionVocabulary owner
Namespace NHow are records named and disambiguated across branches?this ADR
Autonomy UCan work proceed with no link to central services?repo-manager
Reconciliation RWhat happens when branches meet again?repo-manager
Substrate SDoes this namespace hold independently diverging operational state?railiance-platform
+

3. Each plane carries a ladder. Higher is stronger, not better. The right level is the one a namespace can evidence and its risk warrants.

+
N0  no namespace concept; identifiers assume one global space
+N1  namespace implied by deployment, never recorded
+N2  namespace declared; identifiers namespace-scoped; qualification available
+N3  N2 + lineage recorded, and derived identifiers keyed on (namespace, identifier)
+
+U0  routine work requires the central service
+U1  degraded read-only; writes blocked while disconnected
+U2  work proceeds locally: file-derived state written to files, hub-native buffered
+U3  U2 + exercised — a dated disconnection drill with evidence
+
+R0  no defined path; divergence is unrecoverable
+R1  manual, per-record comparison and hand resolution
+R2  append-only events plus derived state: union and re-derive, deterministic
+R3  R2 + lineage-aware; distinguishes divergence from collision automatically
+
+S0  shares operational substrate with another namespace — cannot fork safely
+S1  shared substrate, namespace-keyed
+S2  dedicated substrate, no independent state divergence yet
+S3  independent operational substrate with diverged state — the fork is real
+

4. A namespace declares a posture vector, in the repository rather than the hub, consistent with ADR-010 decision 4 (file-derived state) and ADR-008 decision 5.1.

+
federation:
+  current:  { N: 1, U: 1, R: 1, S: 1 }
+  target:   { N: 3, U: 2, R: 2, S: 1 }
+  reviewed: "2026-08-18"
+  gap:
+    U: "Registration requires the registrar under ADR-007 decision 2 interim.
+        Lifts when derived identifiers land (RMGR-WP-0005-T03)."
+

The ecosystem's own posture today is N1 U1 R1 S1 — one implied namespace, disconnected registration blocked, reconciliation manual, substrate shared. Declaring that is conformant. Claiming better is not.

+

5. Conformance is accuracy, not altitude. Adopted verbatim in force from ADR-008 §06: a namespace is conformant when its declared posture is accurate, its target recorded, and it claims no level it cannot evidence. It is non-conformant when it overclaims, at any altitude.

+

Declaring S0 is conformant. Concealing S0 is not. A repository may join at any posture; it may not join silently. This matters more here than it does for tenancy: the cost of discovering a true posture during reconciliation is the whole difference between T2 and T3.

+

6. Identifiers are unique within a namespace, qualified across. ADR-007 decision 1 is amended: uniqueness and forward-only allocation are namespace-scoped. Global identity is the pair (namespace, identifier).

+
RCLUSTER-WP-0015              this namespace — the common case, unchanged
+RCLUSTER-WP-0015@railiance01  a foreign namespace, explicitly qualified
+

Unqualified always means "in my own namespace", exactly as main does against origin/main. A suffix preserves existing sorting, grep, and tooling; a prefix would break them.

+

7. Derived identifiers key on the pair. ADR-007 decision 2 (C2) derives UUIDv5 from the identifier. Under federation the input must be (namespace, identifier). Deriving from the identifier alone would make two forks holding unrelated work under the same number compute the same UUID — a collision manufactured by the fix. C2 is not yet built, so this is free now and expensive later.

+

8. The planes couple at their upper levels. State the coupling; do not use it to argue the planes are one.

+
  • R3 requires N3 — distinguishing divergence from collision requires lineage.
  • A namespace may not sustain U2 or above while below R2. Operating disconnected without deterministic reconciliation accumulates divergence that cannot later be merged. Autonomy without reconciliation is not federation; it is an unplanned fork.
  • T3 is entailed by S3 in any participant (decision 10).
+

9. Anti-overclaim. This is the most misusable fact in the framework, and it is the direct analogue of ADR-008's P0 → P1 → P2 warning.

+

Adopting namespace-qualified identifiers is movement on the N plane only. It buys disambiguation, citability, and coordinator-free allocation. It does not raise autonomy, reconciliation, or substrate independence by one step. A system at N3 U0 R0 S0 cannot operate disconnected and cannot reconcile.

+

No namespace may be described as "federation-capable", "independently operable", or "able to run disconnected" on N-plane evidence alone. Such a claim requires declared U and R levels with evidence behind them.

+

Commercially, client-facing claims about instance independence must cite the S and U levels, never the identifier scheme. Instance-per-client tenancy is sold on substrate independence; the qualifier does not supply it.

+

10. The reconciliation tier is derived from participants' postures, not judged after the fact.

+
any participant at S3                      -> T3   (regardless of other planes)
+all participants S<=S2 and R>=R2           -> T2   feasible
+any participant below R2                   -> T1   at best; manual thereafter
+

This is the practical payoff of declaring postures: the cost of rejoining is computable before a fork is created, rather than discovered when reconciliation is attempted.

+

11. Coexistence is the normal case; merging is the exception. The qualifier is primarily a coexistence mechanism, not merge preparation. Most forks — client instances above all — are never intended to return. Permanent parallel operation is a first-class outcome, not a failure to reconcile.

+

12. Evidence. A claimed level requires evidence, per ADR-008 §13.

+
LevelEvidence
N2namespace declared in the repo; qualified references resolve
N3lineage fields present; a derived identifier reproduced by an independent implementation
U2work completed with central unreachable, committed, later accepted without rework
U3dated disconnection drill record
R2replaying the union of events reproduces identical derived state
R3a collision and a divergence, correctly distinguished, in test
S2 / S3substrate inventory naming the stateful systems and whether their state has diverged
+

13. Guard. Declared postures regress silently. Posture is checked by the same consistency machinery that checks repository standards (RMGR-WP-0004-T02, rmgr conform), so a namespace that drops below its declared level is a reported defect rather than a discovery. A regression found by guarding is a defect; a regression declared in advance is a decision.

+
+

Reconciliation tiers, and where automation stops

+
TierSituationMechanismAutomatable
T0 Forknamespace created, lineage recordedmetadatayes
T1 Syncpull canon, plans, or knowledge from another namespaceappend events, re-derivelargely
T2 Reintegrationrecords diverged, no participant above S2union events, re-derive, human-resolve genuine contradictionspartly
T3 Amalgamationany participant at S3governed programme — see belowno
+

T3 is not a merge. It resembles the merger or acquisition of distinct companies far more than a version-control merge, and must be planned as such:

+
  • due diligence — inventory both sides, item by item;
  • survivor decisions per subsystem — keep, move, replace, retire;
  • migration with evidence, and decommissioning of what does not survive;
  • governance integration — reconciling two bodies of canon is a human act, never automated;
  • identity, credential, and data custody consolidation.
+

T3 may legitimately end without integration. Permanent coexistence, or divestment, are valid outcomes. Real mergers most often fail at systems integration; an architecture that assumes eventual convergence is lying about its own limits.

+

Known cost

+

prj-state-hub-retirement is a T3 reconciliation inside a single organization — two hub implementations, distinct infrastructure. It required a dedicated project repository, a 425-item disposition inventory (SHR-INV-0001), staged migration with strangler adapters, and explicit retirement gates. That is the realistic cost of T3 under the most favourable conditions possible: one owner, one canon, one credential authority.

+

Nothing here reduces that cost. Declared postures make it visible before a fork is created rather than discovered when reconciliation is attempted.

+
+

Consequences

+

Positive. Disconnected operation stops requiring a coordinator for identity. ADR-007 decision 1's contradiction is resolved rather than tolerated. A namespace mid-journey can describe itself honestly instead of being non-conformant. Reconciliation cost becomes computable in advance. Client instances become expressible.

+

Negative. Every namespace gains a posture to declare and keep accurate, and tooling must learn qualified references. Decision 8's coupling rule constrains disconnected operation to namespaces that can reconcile — deliberately.

+

Deferred. Merge machinery for T2 is not specified here and should not be built until a real fork needs it. T3 needs no machinery by definition; it needs a project repository and human judgement.

+

Amended. ADR-007 decision 1 — uniqueness is namespace-scoped. ADR-007 decision 2 — derivation input becomes (namespace, identifier).

+
+

Open question

+

What is the namespace boundary in practice? Candidates: a fleet instance (railiance01), a client deployment, or an FOS autonomous domain. FOS's recursion — "from projects to companies to foundation-like umbrella structures" — suggests namespaces nest, which would make qualification relative rather than absolute, closer to DNS than to a flat handle. The notation survives either answer, so implementation is not blocked, but the data model is unfinished until it is settled.

+
+

References

+
  • canon/standards/federated-organization-standard_v1.0.md — bounded autonomy, escalation, sovereignty by default, rebuildability
  • ADR-001 — workplans originate as repo files
  • ADR-007 — identifier uniqueness and derived identifiers (amended here)
  • ADR-008 — Multi-Tenancy Framework; source of the plane/ladder/posture form and the accuracy-not-altitude conformance rule
  • ADR-010 — hub authority, local cache, and the two kinds of hub data
  • CUST-WP-0058 — instance-per-client tenancy
  • SHR-INV-0001 — 425-item disposition inventory, T3 cost evidence
  • RMGR-WP-0004-T02 — rmgr conform, the guard machinery
+
CUST-ADR-011 · draft-2 · proposedthe-custodian · canon/architecture/adr-011-federated-namespaces-and-reconciliation-limits.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb
diff --git a/build/adr/custodian-federated-namespaces/v1/revisions/draft-2/index.html b/build/adr/custodian-federated-namespaces/v1/revisions/draft-2/index.html new file mode 100644 index 0000000..99baff5 --- /dev/null +++ b/build/adr/custodian-federated-namespaces/v1/revisions/draft-2/index.html @@ -0,0 +1,284 @@ + + + + +Federated Namespaces + +
CUST-ADR-011 proposed · draft-2 the-custodian reviewed 2026-08-17generated from canonical source — do not edit

Federated Namespaces

Source: the-custodian · canon/architecture/adr-011-federated-namespaces-and-reconciliation-limits.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb

Review due: 2027-02-17

Status

+

Proposed, draft-2. Amends ADR-007 decisions 1 and 2; extends ADR-010 decision 4; adopts the plane/ladder/posture form and the accuracy-not-altitude conformance rule from ADR-008 (Multi-Tenancy Framework).

+
+

Context

+

The ecosystem must be federation-capable — able to work without a live link to central services — and chain-of-command efficient. federated-organization-standard_v1.0 already resolves the organizational half:

+

global coherence is achieved through policy, escalation, and shared protocols rather than through monolithic control (:51) bounded autonomy plus disciplined coordination (:86)

+

Authority is a policy layer; availability is a mechanism. Distributed version control makes the same separation: an integration branch is privileged by agreement, never by a technical property.

+

One accepted decision violates this. ADR-007 decision 1 requires running numbers that are globally unique and allocated forward only. Global sequential allocation requires a coordinator — precisely the central dependency federation must survive. Two disconnected forks each allocating RCLUSTER-WP-0015 is a certainty, not an edge case.

+

This is not hypothetical. Instance-per-client tenancy (CUST-WP-0058) already makes every client deployment a fork of the stack; the business model committed to forking before the identifier scheme could express it.

+

Why this draft changed form

+

Draft-1 stated federation as a set of binary rules — notably "records fork, effects do not". That is a single verdict where a graduated declaration belongs, and it is the same conflation ADR-008 §03 diagnoses for multi-tenancy: "'Is this multi-tenant?' is treated as one question. It is four, and they are independent."

+

"Is this federation-capable?" is likewise not one question. A namespace can be strong on identity and incapable of disconnected operation; it can operate disconnected and have no way to reconcile afterwards. Draft-1 could not say so.

+

This draft reuses ADR-008's vocabulary rather than inventing a parallel one. Two competing maturity vocabularies in one canon would be its own collision.

+
+

Decision

+

1. Records live in a namespace. A namespace is a federated branch of the ecosystem — a fleet instance, a client deployment, an autonomous domain that may operate disconnected. It is the unit of sovereignty in FOS terms and the unit of divergence here.

+

2. Federation is four orthogonal planes.

+
PlaneQuestionVocabulary owner
Namespace NHow are records named and disambiguated across branches?this ADR
Autonomy UCan work proceed with no link to central services?repo-manager
Reconciliation RWhat happens when branches meet again?repo-manager
Substrate SDoes this namespace hold independently diverging operational state?railiance-platform
+

3. Each plane carries a ladder. Higher is stronger, not better. The right level is the one a namespace can evidence and its risk warrants.

+
N0  no namespace concept; identifiers assume one global space
+N1  namespace implied by deployment, never recorded
+N2  namespace declared; identifiers namespace-scoped; qualification available
+N3  N2 + lineage recorded, and derived identifiers keyed on (namespace, identifier)
+
+U0  routine work requires the central service
+U1  degraded read-only; writes blocked while disconnected
+U2  work proceeds locally: file-derived state written to files, hub-native buffered
+U3  U2 + exercised — a dated disconnection drill with evidence
+
+R0  no defined path; divergence is unrecoverable
+R1  manual, per-record comparison and hand resolution
+R2  append-only events plus derived state: union and re-derive, deterministic
+R3  R2 + lineage-aware; distinguishes divergence from collision automatically
+
+S0  shares operational substrate with another namespace — cannot fork safely
+S1  shared substrate, namespace-keyed
+S2  dedicated substrate, no independent state divergence yet
+S3  independent operational substrate with diverged state — the fork is real
+

4. A namespace declares a posture vector, in the repository rather than the hub, consistent with ADR-010 decision 4 (file-derived state) and ADR-008 decision 5.1.

+
federation:
+  current:  { N: 1, U: 1, R: 1, S: 1 }
+  target:   { N: 3, U: 2, R: 2, S: 1 }
+  reviewed: "2026-08-18"
+  gap:
+    U: "Registration requires the registrar under ADR-007 decision 2 interim.
+        Lifts when derived identifiers land (RMGR-WP-0005-T03)."
+

The ecosystem's own posture today is N1 U1 R1 S1 — one implied namespace, disconnected registration blocked, reconciliation manual, substrate shared. Declaring that is conformant. Claiming better is not.

+

5. Conformance is accuracy, not altitude. Adopted verbatim in force from ADR-008 §06: a namespace is conformant when its declared posture is accurate, its target recorded, and it claims no level it cannot evidence. It is non-conformant when it overclaims, at any altitude.

+

Declaring S0 is conformant. Concealing S0 is not. A repository may join at any posture; it may not join silently. This matters more here than it does for tenancy: the cost of discovering a true posture during reconciliation is the whole difference between T2 and T3.

+

6. Identifiers are unique within a namespace, qualified across. ADR-007 decision 1 is amended: uniqueness and forward-only allocation are namespace-scoped. Global identity is the pair (namespace, identifier).

+
RCLUSTER-WP-0015              this namespace — the common case, unchanged
+RCLUSTER-WP-0015@railiance01  a foreign namespace, explicitly qualified
+

Unqualified always means "in my own namespace", exactly as main does against origin/main. A suffix preserves existing sorting, grep, and tooling; a prefix would break them.

+

7. Derived identifiers key on the pair. ADR-007 decision 2 (C2) derives UUIDv5 from the identifier. Under federation the input must be (namespace, identifier). Deriving from the identifier alone would make two forks holding unrelated work under the same number compute the same UUID — a collision manufactured by the fix. C2 is not yet built, so this is free now and expensive later.

+

8. The planes couple at their upper levels. State the coupling; do not use it to argue the planes are one.

+
  • R3 requires N3 — distinguishing divergence from collision requires lineage.
  • A namespace may not sustain U2 or above while below R2. Operating disconnected without deterministic reconciliation accumulates divergence that cannot later be merged. Autonomy without reconciliation is not federation; it is an unplanned fork.
  • T3 is entailed by S3 in any participant (decision 10).
+

9. Anti-overclaim. This is the most misusable fact in the framework, and it is the direct analogue of ADR-008's P0 → P1 → P2 warning.

+

Adopting namespace-qualified identifiers is movement on the N plane only. It buys disambiguation, citability, and coordinator-free allocation. It does not raise autonomy, reconciliation, or substrate independence by one step. A system at N3 U0 R0 S0 cannot operate disconnected and cannot reconcile.

+

No namespace may be described as "federation-capable", "independently operable", or "able to run disconnected" on N-plane evidence alone. Such a claim requires declared U and R levels with evidence behind them.

+

Commercially, client-facing claims about instance independence must cite the S and U levels, never the identifier scheme. Instance-per-client tenancy is sold on substrate independence; the qualifier does not supply it.

+

10. The reconciliation tier is derived from participants' postures, not judged after the fact.

+
any participant at S3                      -> T3   (regardless of other planes)
+all participants S<=S2 and R>=R2           -> T2   feasible
+any participant below R2                   -> T1   at best; manual thereafter
+

This is the practical payoff of declaring postures: the cost of rejoining is computable before a fork is created, rather than discovered when reconciliation is attempted.

+

11. Coexistence is the normal case; merging is the exception. The qualifier is primarily a coexistence mechanism, not merge preparation. Most forks — client instances above all — are never intended to return. Permanent parallel operation is a first-class outcome, not a failure to reconcile.

+

12. Evidence. A claimed level requires evidence, per ADR-008 §13.

+
LevelEvidence
N2namespace declared in the repo; qualified references resolve
N3lineage fields present; a derived identifier reproduced by an independent implementation
U2work completed with central unreachable, committed, later accepted without rework
U3dated disconnection drill record
R2replaying the union of events reproduces identical derived state
R3a collision and a divergence, correctly distinguished, in test
S2 / S3substrate inventory naming the stateful systems and whether their state has diverged
+

13. Guard. Declared postures regress silently. Posture is checked by the same consistency machinery that checks repository standards (RMGR-WP-0004-T02, rmgr conform), so a namespace that drops below its declared level is a reported defect rather than a discovery. A regression found by guarding is a defect; a regression declared in advance is a decision.

+
+

Reconciliation tiers, and where automation stops

+
TierSituationMechanismAutomatable
T0 Forknamespace created, lineage recordedmetadatayes
T1 Syncpull canon, plans, or knowledge from another namespaceappend events, re-derivelargely
T2 Reintegrationrecords diverged, no participant above S2union events, re-derive, human-resolve genuine contradictionspartly
T3 Amalgamationany participant at S3governed programme — see belowno
+

T3 is not a merge. It resembles the merger or acquisition of distinct companies far more than a version-control merge, and must be planned as such:

+
  • due diligence — inventory both sides, item by item;
  • survivor decisions per subsystem — keep, move, replace, retire;
  • migration with evidence, and decommissioning of what does not survive;
  • governance integration — reconciling two bodies of canon is a human act, never automated;
  • identity, credential, and data custody consolidation.
+

T3 may legitimately end without integration. Permanent coexistence, or divestment, are valid outcomes. Real mergers most often fail at systems integration; an architecture that assumes eventual convergence is lying about its own limits.

+

Known cost

+

prj-state-hub-retirement is a T3 reconciliation inside a single organization — two hub implementations, distinct infrastructure. It required a dedicated project repository, a 425-item disposition inventory (SHR-INV-0001), staged migration with strangler adapters, and explicit retirement gates. That is the realistic cost of T3 under the most favourable conditions possible: one owner, one canon, one credential authority.

+

Nothing here reduces that cost. Declared postures make it visible before a fork is created rather than discovered when reconciliation is attempted.

+
+

Consequences

+

Positive. Disconnected operation stops requiring a coordinator for identity. ADR-007 decision 1's contradiction is resolved rather than tolerated. A namespace mid-journey can describe itself honestly instead of being non-conformant. Reconciliation cost becomes computable in advance. Client instances become expressible.

+

Negative. Every namespace gains a posture to declare and keep accurate, and tooling must learn qualified references. Decision 8's coupling rule constrains disconnected operation to namespaces that can reconcile — deliberately.

+

Deferred. Merge machinery for T2 is not specified here and should not be built until a real fork needs it. T3 needs no machinery by definition; it needs a project repository and human judgement.

+

Amended. ADR-007 decision 1 — uniqueness is namespace-scoped. ADR-007 decision 2 — derivation input becomes (namespace, identifier).

+
+

Open question

+

What is the namespace boundary in practice? Candidates: a fleet instance (railiance01), a client deployment, or an FOS autonomous domain. FOS's recursion — "from projects to companies to foundation-like umbrella structures" — suggests namespaces nest, which would make qualification relative rather than absolute, closer to DNS than to a flat handle. The notation survives either answer, so implementation is not blocked, but the data model is unfinished until it is settled.

+
+

References

+
  • canon/standards/federated-organization-standard_v1.0.md — bounded autonomy, escalation, sovereignty by default, rebuildability
  • ADR-001 — workplans originate as repo files
  • ADR-007 — identifier uniqueness and derived identifiers (amended here)
  • ADR-008 — Multi-Tenancy Framework; source of the plane/ladder/posture form and the accuracy-not-altitude conformance rule
  • ADR-010 — hub authority, local cache, and the two kinds of hub data
  • CUST-WP-0058 — instance-per-client tenancy
  • SHR-INV-0001 — 425-item disposition inventory, T3 cost evidence
  • RMGR-WP-0004-T02 — rmgr conform, the guard machinery
+
CUST-ADR-011 · draft-2 · proposedthe-custodian · canon/architecture/adr-011-federated-namespaces-and-reconciliation-limits.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb
diff --git a/build/adr/custodian-hub-authority/v1/index.html b/build/adr/custodian-hub-authority/v1/index.html new file mode 100644 index 0000000..b35a479 --- /dev/null +++ b/build/adr/custodian-hub-authority/v1/index.html @@ -0,0 +1,238 @@ + + + + +Hub Authority, Local Cache, and the Two Kinds of Hub Data + +
CUST-ADR-010 proposed · draft-1 the-custodian reviewed 2026-08-17generated from canonical source — do not edit

Hub Authority, Local Cache, and the Two Kinds of Hub Data

Source: the-custodian · canon/architecture/adr-010-hub-authority-and-local-cache-model.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb

Review due: 2027-02-17

Status

+

Proposed.

+
+

Context

+

Investigating a workplan-identifier flip-flop (ADR-007) revealed that two State Hub instances were operating as peer databases, not as a primary and a replica:

+
AddressInstanceWorkplans
127.0.0.1:8000 (IPv4)local uvicorn on docker postgres955
[::1]:8000 (IPv6)ssh tunnel state-hub-primary → railiance01649
+

Both listen on port 8000, separated only by IP family, so every tool defaulting to 127.0.0.1 reached the local instance while believing it was the primary.

+

Measured divergence — 320 records exist locally but not on the primary:

+
backed by a file that exists on disk    288    fully rebuildable
+no backing file recorded                 28    not rebuildable as-is
+same filename, different UUID             4    duplicate registration
+

No file was missing for any of the 288. The divergence is therefore almost entirely redundant: it can be discarded and rebuilt from repositories without losing anything.

+

ADR-001 already says work originates as repository files and the hub is a read model. The two-peer-database situation contradicts that in practice: a second database accumulated 306 net records of its own.

+
+

Decision

+

1. One authoritative hub, deriving from repository files. The central State Hub — running on railiance — is authoritative. It is authoritative as a reading of the repositories, not as a second place data lives. Repository files remain the source of truth (ADR-001).

+

2. A local hub is a cache, never a database. Local instances hold a rebuildable projection. A cache may be discarded and reconstructed from the repositories at any time, and losing it must never lose work.

+

This replaces the peer-database arrangement. It is also why the divergence is tractable: a divergent database is a merge problem, a stale cache is a refresh problem.

+

3. Local work requires no hub at all. Repository files are self-describing — identifier, status, tasks, all in frontmatter. Working in a repository requires reading files, not querying an index. A cache is an optimization for cross-repo questions, never a prerequisite for doing work.

+

4. Hub data is classified by origin, and the two kinds have opposite rules.

+
File-derivedHub-native
Examplesworkplans, tasks, statuses, dependenciesprogress events, decisions, inbox messages, token events
Source of truththe repository filethe hub
Offline behaviourwrite the file and commit — the commit is the writebuffer locally, replay when reachable
Conflict modelnone; conflicts are git conflicts, resolved in gitnone; append-only merges regardless of order
Central accepts pushes?no — it derivesyes
+

Neither kind needs a hub-side conflict model. That is the point of the split: if central derives file-backed state, it cannot hold a conflicting version of it — it re-derives whatever git settles on. Two people editing one workplan is a git conflict and belongs to git.

+

5. Central derives file-backed state; it does not accept pushes of it. "Authoritative" means authoritative reading, so nothing may inject derived state directly. Hub-native records are the exception and keep a real write path.

+

6. Preliminary until confirmed. Locally registered data and uncommitted repository state are preliminary until the central service has seen them. Mitigation is by changing the repository files and the local cache — never by editing central to match a local view.

+

Combined with ADR-007 decision 2 (identifiers derived from PREFIX-WP-NNNN), "preliminary" largely stops mattering: a cache computes the same identifier central will, so offline-registered data is already correct on arrival and needs confirmation rather than reconciliation.

+

7. Every record has exactly one authoritative hub. The State Hub retirement splits one hub into several. Multiple central hubs are permitted only under this rule: the owning hub is determined by the record's repository and domain. Without it, the same peer-database divergence recurs at larger scale.

+

8. Cache reads are advisory and must carry their age. Cross-repo answers from a cache are advisory and should be presented with staleness. For the repository an agent is working in, the file is truth and the cache is never consulted for correctness.

+
+

Orphan disposition

+

The 28 records with no backing file are the only ones a cache rebuild would drop. They fall into three classes, to be separated before any rebuild:

+
  1. Broken links — a file exists but backing_filename was never recorded. RMGR-WP-0004 is one: the workplan file exists and is committed. These are metadata repairs, not data loss, and are likely the largest class.
  2. Live hub-first records — proposed, ready, or backlog with no file, in activity-core, core-hub, hub-core, issue-core, ops-hub, prj-forgejo-org-refactor, railiance-enablement, railiance-infra, reef-railiance. Each needs a repository file written or an explicit drop. These are ADR-001 violations and must not be preserved as hub-only records.
  3. Closed hub-first records — finished or archived with no file. Retain as historical provenance where cheap; do not reconstruct plans that are done.
+

A cache rebuild enforces ADR-001 retroactively: the only casualties are records that broke it.

+
+

Consequences

+

Positive. The divergence becomes discardable rather than mergeable. Offline work is fully supported without a write buffer for file-backed state — the git commit is the write. No hub-side conflict model is needed for either data kind. Authority stops being a policy claim and becomes a structural property.

+

Negative. The 28 orphans require case-by-case disposition before a rebuild. Any consumer that treats a local hub as authoritative must be corrected. The one-hub-per-record rule constrains the retirement's hub split.

+

Rescoping. STATE-WP-0068 (offline write buffer and edge relay) is scoped as a single mechanism. Under decision 4, most of what it buffers does not need buffering — only the append-only hub-native stream does. Its scope should be re-examined before more is built on it; this may reduce work rather than add it.

+

Correction to ADR-007. Decision 2 there calls the workstation instance a "development read replica". It was neither a replica nor smaller — it held 306 more workplans than the primary. Superseded by decisions 1–3 here.

+
+

Implementation

+

Owned by repo-manager for file-derived state (decision 747011c6; it already owns repository representation, file-backed record indexing, and reconciliation) and by hub-core for hub-native records. Tracked under RMGR-WP-0005.

+
+

References

+
  • ADR-001 — workplans originate as repo files; hub is a read model
  • ADR-007 — identifier uniqueness, derived identifiers, worker topology
  • Decision 747011c6 — repository standards belong to Repo Manager
  • RMGR-WP-0005 — registrar consolidation and deterministic identifiers
  • STATE-WP-0068 — offline write buffer and edge relay (rescope candidate)
  • Divergence measurement, 2026-08-17: 955 local / 649 primary / 320 local-only
+
CUST-ADR-010 · draft-1 · proposedthe-custodian · canon/architecture/adr-010-hub-authority-and-local-cache-model.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb
diff --git a/build/adr/custodian-hub-authority/v1/revisions/draft-1/index.html b/build/adr/custodian-hub-authority/v1/revisions/draft-1/index.html new file mode 100644 index 0000000..b35a479 --- /dev/null +++ b/build/adr/custodian-hub-authority/v1/revisions/draft-1/index.html @@ -0,0 +1,238 @@ + + + + +Hub Authority, Local Cache, and the Two Kinds of Hub Data + +
CUST-ADR-010 proposed · draft-1 the-custodian reviewed 2026-08-17generated from canonical source — do not edit

Hub Authority, Local Cache, and the Two Kinds of Hub Data

Source: the-custodian · canon/architecture/adr-010-hub-authority-and-local-cache-model.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb

Review due: 2027-02-17

Status

+

Proposed.

+
+

Context

+

Investigating a workplan-identifier flip-flop (ADR-007) revealed that two State Hub instances were operating as peer databases, not as a primary and a replica:

+
AddressInstanceWorkplans
127.0.0.1:8000 (IPv4)local uvicorn on docker postgres955
[::1]:8000 (IPv6)ssh tunnel state-hub-primary → railiance01649
+

Both listen on port 8000, separated only by IP family, so every tool defaulting to 127.0.0.1 reached the local instance while believing it was the primary.

+

Measured divergence — 320 records exist locally but not on the primary:

+
backed by a file that exists on disk    288    fully rebuildable
+no backing file recorded                 28    not rebuildable as-is
+same filename, different UUID             4    duplicate registration
+

No file was missing for any of the 288. The divergence is therefore almost entirely redundant: it can be discarded and rebuilt from repositories without losing anything.

+

ADR-001 already says work originates as repository files and the hub is a read model. The two-peer-database situation contradicts that in practice: a second database accumulated 306 net records of its own.

+
+

Decision

+

1. One authoritative hub, deriving from repository files. The central State Hub — running on railiance — is authoritative. It is authoritative as a reading of the repositories, not as a second place data lives. Repository files remain the source of truth (ADR-001).

+

2. A local hub is a cache, never a database. Local instances hold a rebuildable projection. A cache may be discarded and reconstructed from the repositories at any time, and losing it must never lose work.

+

This replaces the peer-database arrangement. It is also why the divergence is tractable: a divergent database is a merge problem, a stale cache is a refresh problem.

+

3. Local work requires no hub at all. Repository files are self-describing — identifier, status, tasks, all in frontmatter. Working in a repository requires reading files, not querying an index. A cache is an optimization for cross-repo questions, never a prerequisite for doing work.

+

4. Hub data is classified by origin, and the two kinds have opposite rules.

+
File-derivedHub-native
Examplesworkplans, tasks, statuses, dependenciesprogress events, decisions, inbox messages, token events
Source of truththe repository filethe hub
Offline behaviourwrite the file and commit — the commit is the writebuffer locally, replay when reachable
Conflict modelnone; conflicts are git conflicts, resolved in gitnone; append-only merges regardless of order
Central accepts pushes?no — it derivesyes
+

Neither kind needs a hub-side conflict model. That is the point of the split: if central derives file-backed state, it cannot hold a conflicting version of it — it re-derives whatever git settles on. Two people editing one workplan is a git conflict and belongs to git.

+

5. Central derives file-backed state; it does not accept pushes of it. "Authoritative" means authoritative reading, so nothing may inject derived state directly. Hub-native records are the exception and keep a real write path.

+

6. Preliminary until confirmed. Locally registered data and uncommitted repository state are preliminary until the central service has seen them. Mitigation is by changing the repository files and the local cache — never by editing central to match a local view.

+

Combined with ADR-007 decision 2 (identifiers derived from PREFIX-WP-NNNN), "preliminary" largely stops mattering: a cache computes the same identifier central will, so offline-registered data is already correct on arrival and needs confirmation rather than reconciliation.

+

7. Every record has exactly one authoritative hub. The State Hub retirement splits one hub into several. Multiple central hubs are permitted only under this rule: the owning hub is determined by the record's repository and domain. Without it, the same peer-database divergence recurs at larger scale.

+

8. Cache reads are advisory and must carry their age. Cross-repo answers from a cache are advisory and should be presented with staleness. For the repository an agent is working in, the file is truth and the cache is never consulted for correctness.

+
+

Orphan disposition

+

The 28 records with no backing file are the only ones a cache rebuild would drop. They fall into three classes, to be separated before any rebuild:

+
  1. Broken links — a file exists but backing_filename was never recorded. RMGR-WP-0004 is one: the workplan file exists and is committed. These are metadata repairs, not data loss, and are likely the largest class.
  2. Live hub-first records — proposed, ready, or backlog with no file, in activity-core, core-hub, hub-core, issue-core, ops-hub, prj-forgejo-org-refactor, railiance-enablement, railiance-infra, reef-railiance. Each needs a repository file written or an explicit drop. These are ADR-001 violations and must not be preserved as hub-only records.
  3. Closed hub-first records — finished or archived with no file. Retain as historical provenance where cheap; do not reconstruct plans that are done.
+

A cache rebuild enforces ADR-001 retroactively: the only casualties are records that broke it.

+
+

Consequences

+

Positive. The divergence becomes discardable rather than mergeable. Offline work is fully supported without a write buffer for file-backed state — the git commit is the write. No hub-side conflict model is needed for either data kind. Authority stops being a policy claim and becomes a structural property.

+

Negative. The 28 orphans require case-by-case disposition before a rebuild. Any consumer that treats a local hub as authoritative must be corrected. The one-hub-per-record rule constrains the retirement's hub split.

+

Rescoping. STATE-WP-0068 (offline write buffer and edge relay) is scoped as a single mechanism. Under decision 4, most of what it buffers does not need buffering — only the append-only hub-native stream does. Its scope should be re-examined before more is built on it; this may reduce work rather than add it.

+

Correction to ADR-007. Decision 2 there calls the workstation instance a "development read replica". It was neither a replica nor smaller — it held 306 more workplans than the primary. Superseded by decisions 1–3 here.

+
+

Implementation

+

Owned by repo-manager for file-derived state (decision 747011c6; it already owns repository representation, file-backed record indexing, and reconciliation) and by hub-core for hub-native records. Tracked under RMGR-WP-0005.

+
+

References

+
  • ADR-001 — workplans originate as repo files; hub is a read model
  • ADR-007 — identifier uniqueness, derived identifiers, worker topology
  • Decision 747011c6 — repository standards belong to Repo Manager
  • RMGR-WP-0005 — registrar consolidation and deterministic identifiers
  • STATE-WP-0068 — offline write buffer and edge relay (rescope candidate)
  • Divergence measurement, 2026-08-17: 955 local / 649 primary / 320 local-only
+
CUST-ADR-010 · draft-1 · proposedthe-custodian · canon/architecture/adr-010-hub-authority-and-local-cache-model.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb
diff --git a/build/adr/custodian-materialized-derived-state/v1/index.html b/build/adr/custodian-materialized-derived-state/v1/index.html new file mode 100644 index 0000000..28b8e5a --- /dev/null +++ b/build/adr/custodian-materialized-derived-state/v1/index.html @@ -0,0 +1,244 @@ + + + + +Materialized Derived State with Fingerprint Invalidation for Repo-Sourced Data + +
CUST-ADR-003 accepted · accepted-1 the-custodian reviewed 2026-03-20generated from canonical source — do not edit

Materialized Derived State with Fingerprint Invalidation for Repo-Sourced Data

Source: the-custodian · canon/architecture/adr-003-materialized-derived-state.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb

Review due: 2026-09-20

Status

+

Accepted.

+
+

Context

+

The Custodian State Hub is a read model (CQRS terminology) — its data is fully derivable from canonical sources that live in repositories and the filesystem. No state-hub data is authoritative; it is always a derived view of what the repos contain.

+

Several categories of data fit this description:

+
DataCanonical sourceState-hub table
SBOM dependenciesuv.lock, package-lock.json, etc.sbom_entries
Third-party service declarationstpsc.yamltpsc_entries
Provided capabilitiesSCOPE.md capability blockscapability_catalog
DoI compliance tier14 criteria across repo files + DBdoi_cache
Workplan task statusworkplans/*.mdtasks
+

Early implementations either recomputed this data on every request (too slow) or ingested it once without invalidation (stale data goes undetected). Neither is acceptable for a system designed to give accurate, fast orientation.

+

The doi_cache table, introduced in CUST-WP-0024, demonstrated a pattern that solves both problems. This ADR formalises that pattern and mandates its use for all repo-sourced derived data.

+
+

Pattern Name

+

Materialized Derived State with Fingerprint Invalidation.

+

This pattern is known under several names in the literature:

+
  • Materialized View (SQL standard, PostgreSQL) — the stored result of a query or computation, refreshed on demand when source data changes.
  • Derived Data Store (Kleppmann, Designing Data-Intensive Applications, Ch. 3 & 11) — a system whose entire dataset can be rebuilt from upstream sources; it is never the source of truth.
  • Read Model / Projection (CQRS / Event Sourcing) — a pre-computed view maintained alongside a write model, rebuilt when relevant events occur.
  • Fingerprint-based / Content-addressed invalidation — analogous to HTTP ETags: a cache entry is valid as long as a composite hash/timestamp of its inputs matches the stored value.
+

The State Hub already documents itself as a read model. This ADR extends that principle to specify how the read model stays fresh.

+
+

Decision

+

1. All repo-sourced derived data MUST be materialised in the DB

+

Data computed from repository files or repo records must be stored in a dedicated table rather than recomputed per request. Direct computation on every API call is only permissible for development tooling or when explicitly forced by the caller.

+

2. Each materialised table MUST carry a fingerprint column

+

The fingerprint is a deterministic string encoding all inputs that affect the computed result. It is compared on each read; if unchanged, the stored result is returned without recomputation. If changed, the result is recomputed and the stored value is updated.

+

Fingerprint composition rules:

+
  • Include the updated_at timestamp of every DB record that feeds the computation (repo record, related domain, goals, snapshots).
  • Include the mtime (filesystem modification time) of every file that feeds the computation (SCOPE.md, CLAUDE.md, lockfiles, tpsc.yaml, etc.).
  • Join all components with | as a pipe-separated string — no hashing needed since the string is compared by equality, not transmitted to clients.
  • If a file is absent, encode filename:absent rather than omitting it, so file creation also triggers invalidation.
+

Reference implementation: state-hub/api/doi_engine.py::compute_fingerprint()

+

3. Every materialised endpoint MUST support ?force_refresh=true

+

Callers must always be able to bypass the cache and trigger a fresh computation. This is the escape hatch for debugging, post-ingest verification, and scheduled background refresh jobs.

+

4. Writes to source data SHOULD update the repo record's updated_at

+

Operations that change source data (SBOM ingest, TPSC ingest, capability ingest) must ensure managed_repos.updated_at is refreshed so the fingerprint detects the change on the next read. Where data lives in a related table (e.g. tpsc_snapshots), the fingerprint must include that table's max(snapshot_at) directly rather than relying on the repo record.

+

5. The DB is never the source of truth — the rebuild principle holds

+

Per ADR-001, the state-hub must be rebuildable from scratch by re-ingesting all canonical sources. Materialised tables are caches, not records of authority. They may be wiped and repopulated at any time without data loss. This means:

+
  • No materialised table may be the only copy of any information.
  • Schema migrations that wipe a materialised table are safe and expected.
  • Background jobs that periodically re-ingest all repos are valid and encouraged.
+
+

Consequences

+

Positive

+
  • Fast reads in steady state — after the first computation, subsequent reads hit the DB with no filesystem or subprocess overhead.
  • Accurate on change — fingerprint invalidation ensures stale data is never silently served; the cache refreshes exactly when needed.
  • Debuggable — force_refresh=true and checked_at timestamps make it easy to see when a value was last computed and to trigger a recheck.
  • Consistent with the read model principle — the pattern makes explicit what was always implied: state-hub data is derived, not authoritative.
+

Negative / Trade-offs

+
  • First-call latency — cache misses are expensive (filesystem reads, subprocess calls, HTTP self-calls). Mitigated by pre-warming caches at startup or after ingest.
  • Fingerprint completeness — if a new input is added to a computation and not added to the fingerprint, stale results will be silently returned. The fingerprint must be kept in sync with the computation.
  • Filesystem dependency — file mtimes are volatile (e.g. git checkout rewrites mtimes). In practice this means a cache miss after every checkout, not a correctness problem.
+
+

Implementation Checklist

+

When adding a new category of repo-sourced derived data:

+
  • [ ] Create a _cache or _snapshots table with fingerprint and checked_at columns.
  • [ ] Implement compute_fingerprint(repo, ...) in the relevant module.
  • [ ] Add ?force_refresh=true query parameter to the read endpoint.
  • [ ] Ensure the ingest script (or write path) touches managed_repos.updated_at or includes a related table's max(timestamp) in the fingerprint.
  • [ ] Verify the cache can be wiped and repopulated without data loss.
  • [ ] Document which inputs are included in the fingerprint in a comment alongside compute_fingerprint.
+
+

Current Implementations

+
Derived dataTableFingerprint inputsForce-refresh
DoI compliance tierdoi_cacherepo.updated_at, max(tpsc_snapshots.snapshot_at), max(repo_goals.updated_at), mtime(SCOPE.md), mtime(CLAUDE.md), mtime(tpsc.yaml)?force_refresh=true
+
+

Planned Applications

+
Derived dataTable (proposed)Notes
SBOM summary statssbom_cacheFingerprint: max(sbom_snapshots.snapshot_at)
Capability declarationscapability_cacheFingerprint: mtime(SCOPE.md), repo.updated_at
Workplan status summaryAlready handled by consistency checkerFingerprint: workplan file mtimes
+
+
CUST-ADR-003 · accepted-1 · acceptedthe-custodian · canon/architecture/adr-003-materialized-derived-state.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb
diff --git a/build/adr/custodian-materialized-derived-state/v1/revisions/accepted-1/index.html b/build/adr/custodian-materialized-derived-state/v1/revisions/accepted-1/index.html new file mode 100644 index 0000000..28b8e5a --- /dev/null +++ b/build/adr/custodian-materialized-derived-state/v1/revisions/accepted-1/index.html @@ -0,0 +1,244 @@ + + + + +Materialized Derived State with Fingerprint Invalidation for Repo-Sourced Data + +
CUST-ADR-003 accepted · accepted-1 the-custodian reviewed 2026-03-20generated from canonical source — do not edit

Materialized Derived State with Fingerprint Invalidation for Repo-Sourced Data

Source: the-custodian · canon/architecture/adr-003-materialized-derived-state.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb

Review due: 2026-09-20

Status

+

Accepted.

+
+

Context

+

The Custodian State Hub is a read model (CQRS terminology) — its data is fully derivable from canonical sources that live in repositories and the filesystem. No state-hub data is authoritative; it is always a derived view of what the repos contain.

+

Several categories of data fit this description:

+
DataCanonical sourceState-hub table
SBOM dependenciesuv.lock, package-lock.json, etc.sbom_entries
Third-party service declarationstpsc.yamltpsc_entries
Provided capabilitiesSCOPE.md capability blockscapability_catalog
DoI compliance tier14 criteria across repo files + DBdoi_cache
Workplan task statusworkplans/*.mdtasks
+

Early implementations either recomputed this data on every request (too slow) or ingested it once without invalidation (stale data goes undetected). Neither is acceptable for a system designed to give accurate, fast orientation.

+

The doi_cache table, introduced in CUST-WP-0024, demonstrated a pattern that solves both problems. This ADR formalises that pattern and mandates its use for all repo-sourced derived data.

+
+

Pattern Name

+

Materialized Derived State with Fingerprint Invalidation.

+

This pattern is known under several names in the literature:

+
  • Materialized View (SQL standard, PostgreSQL) — the stored result of a query or computation, refreshed on demand when source data changes.
  • Derived Data Store (Kleppmann, Designing Data-Intensive Applications, Ch. 3 & 11) — a system whose entire dataset can be rebuilt from upstream sources; it is never the source of truth.
  • Read Model / Projection (CQRS / Event Sourcing) — a pre-computed view maintained alongside a write model, rebuilt when relevant events occur.
  • Fingerprint-based / Content-addressed invalidation — analogous to HTTP ETags: a cache entry is valid as long as a composite hash/timestamp of its inputs matches the stored value.
+

The State Hub already documents itself as a read model. This ADR extends that principle to specify how the read model stays fresh.

+
+

Decision

+

1. All repo-sourced derived data MUST be materialised in the DB

+

Data computed from repository files or repo records must be stored in a dedicated table rather than recomputed per request. Direct computation on every API call is only permissible for development tooling or when explicitly forced by the caller.

+

2. Each materialised table MUST carry a fingerprint column

+

The fingerprint is a deterministic string encoding all inputs that affect the computed result. It is compared on each read; if unchanged, the stored result is returned without recomputation. If changed, the result is recomputed and the stored value is updated.

+

Fingerprint composition rules:

+
  • Include the updated_at timestamp of every DB record that feeds the computation (repo record, related domain, goals, snapshots).
  • Include the mtime (filesystem modification time) of every file that feeds the computation (SCOPE.md, CLAUDE.md, lockfiles, tpsc.yaml, etc.).
  • Join all components with | as a pipe-separated string — no hashing needed since the string is compared by equality, not transmitted to clients.
  • If a file is absent, encode filename:absent rather than omitting it, so file creation also triggers invalidation.
+

Reference implementation: state-hub/api/doi_engine.py::compute_fingerprint()

+

3. Every materialised endpoint MUST support ?force_refresh=true

+

Callers must always be able to bypass the cache and trigger a fresh computation. This is the escape hatch for debugging, post-ingest verification, and scheduled background refresh jobs.

+

4. Writes to source data SHOULD update the repo record's updated_at

+

Operations that change source data (SBOM ingest, TPSC ingest, capability ingest) must ensure managed_repos.updated_at is refreshed so the fingerprint detects the change on the next read. Where data lives in a related table (e.g. tpsc_snapshots), the fingerprint must include that table's max(snapshot_at) directly rather than relying on the repo record.

+

5. The DB is never the source of truth — the rebuild principle holds

+

Per ADR-001, the state-hub must be rebuildable from scratch by re-ingesting all canonical sources. Materialised tables are caches, not records of authority. They may be wiped and repopulated at any time without data loss. This means:

+
  • No materialised table may be the only copy of any information.
  • Schema migrations that wipe a materialised table are safe and expected.
  • Background jobs that periodically re-ingest all repos are valid and encouraged.
+
+

Consequences

+

Positive

+
  • Fast reads in steady state — after the first computation, subsequent reads hit the DB with no filesystem or subprocess overhead.
  • Accurate on change — fingerprint invalidation ensures stale data is never silently served; the cache refreshes exactly when needed.
  • Debuggable — force_refresh=true and checked_at timestamps make it easy to see when a value was last computed and to trigger a recheck.
  • Consistent with the read model principle — the pattern makes explicit what was always implied: state-hub data is derived, not authoritative.
+

Negative / Trade-offs

+
  • First-call latency — cache misses are expensive (filesystem reads, subprocess calls, HTTP self-calls). Mitigated by pre-warming caches at startup or after ingest.
  • Fingerprint completeness — if a new input is added to a computation and not added to the fingerprint, stale results will be silently returned. The fingerprint must be kept in sync with the computation.
  • Filesystem dependency — file mtimes are volatile (e.g. git checkout rewrites mtimes). In practice this means a cache miss after every checkout, not a correctness problem.
+
+

Implementation Checklist

+

When adding a new category of repo-sourced derived data:

+
  • [ ] Create a _cache or _snapshots table with fingerprint and checked_at columns.
  • [ ] Implement compute_fingerprint(repo, ...) in the relevant module.
  • [ ] Add ?force_refresh=true query parameter to the read endpoint.
  • [ ] Ensure the ingest script (or write path) touches managed_repos.updated_at or includes a related table's max(timestamp) in the fingerprint.
  • [ ] Verify the cache can be wiped and repopulated without data loss.
  • [ ] Document which inputs are included in the fingerprint in a comment alongside compute_fingerprint.
+
+

Current Implementations

+
Derived dataTableFingerprint inputsForce-refresh
DoI compliance tierdoi_cacherepo.updated_at, max(tpsc_snapshots.snapshot_at), max(repo_goals.updated_at), mtime(SCOPE.md), mtime(CLAUDE.md), mtime(tpsc.yaml)?force_refresh=true
+
+

Planned Applications

+
Derived dataTable (proposed)Notes
SBOM summary statssbom_cacheFingerprint: max(sbom_snapshots.snapshot_at)
Capability declarationscapability_cacheFingerprint: mtime(SCOPE.md), repo.updated_at
Workplan status summaryAlready handled by consistency checkerFingerprint: workplan file mtimes
+
+
CUST-ADR-003 · accepted-1 · acceptedthe-custodian · canon/architecture/adr-003-materialized-derived-state.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb
diff --git a/build/adr/custodian-workplan-identity/v1/index.html b/build/adr/custodian-workplan-identity/v1/index.html new file mode 100644 index 0000000..9bc4cef --- /dev/null +++ b/build/adr/custodian-workplan-identity/v1/index.html @@ -0,0 +1,278 @@ + + + + +Workplan Identity Uniqueness, Single Registrar, and Repo Worker Topology + +
CUST-ADR-007 accepted · accepted-1 the-custodian reviewed 2026-08-17generated from canonical source — do not edit

Workplan Identity Uniqueness, Single Registrar, and Repo Worker Topology

Source: the-custodian · canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb

Review due: 2027-02-17

Status

+

Accepted 2026-08-17. Identifier uniqueness, the registrar model, lifecycle protection, and worker topology are settled.

+

Remediation of existing collisions (§ Migration) remains an open ruling. It is disruptive, touches six repositories, and no active work depends on it — all five duplicated identifiers are finished.

+
+

Context

+

On 2026-08-16, STATE-WP-0080 was found registered twice, in two different databases, with two different workplan UUIDs and two disjoint sets of task UUIDs:

+
RegistrarWorkplan UUIDReachable at 127.0.0.1:8000
Workstation hub (make api, local postgres)03f38314yes
A second instance, over a second databasebbfce36a404
+

The second instance is not identifiable from the commit author. custodian-sync@railiance.local is a hardcoded default git identity in scripts/consistency_check.py:1899 (GIT_SYNC_USER_NAME / GIT_SYNC_USER_EMAIL), so every machine running fix-consistency commits under that name. The discriminator is the timezone: sync commits appear under both +0000 and +0200 (the workstation's offset), which is independent evidence of two machines writing to one repository.

+

Both write their IDs into the same git-tracked workplan file, so each sync overwrites the other's IDs and the file flip-flops on every round trip. The same commit (ff909e1, "renormalize lifecycle state [auto]") also promoted the workplan proposed → active without human review.

+

A fleet scan of 955 hub workplans (525 with parseable PREFIX-WP-NNNN identifiers) found this is not an isolated incident. Two distinct identity defects are live:

+

Prefix reuse across repositories:

+
CUST-WP-      → state-hub, the-custodian
+RAIL-BS-WP-   → railiance-bootstrap, railiance-cluster
+RAILIANCE-WP- → railiance-apps, railiance-forge, railiance-platform, railiance-telemetry
+

PRJ-WP- is a latent fourth: statehub register derives it from the prj- flavor marker, so every project repository would collide (see RMGR-WP-0004).

+

Running-number reuse:

+
CUST-WP-0000       the-custodian ×2
+CUST-WP-0010       the-custodian ×2
+CUST-WP-0045       the-custodian ×2
+RAILIANCE-WP-0015  railiance-platform, railiance-apps
+RAILIANCE-WP-0016  railiance-platform ×2, railiance-apps
+

RAILIANCE-WP-0015 is actively cited in operational memory as the cnpg-backup gate in railiance-apps; a second record of the same name in railiance-platform makes that citation ambiguous.

+

The C-26 consistency check already flags prefix nonconformance within a repo against a canonical prefix, but nothing enforces uniqueness across repos, and nothing prevents number reuse.

+
+

Decision

+

1. A workplan identifier is globally unique. PREFIX-WP-NNNN names exactly one workplan across the entire fleet, for all time.

+

Amended 2026-08-17 by ADR-011 decision 2. Uniqueness and forward-only allocation are namespace-scoped, not global; global identity is the pair (namespace, identifier), written PREFIX-WP-NNNN@namespace when foreign. Global sequential allocation would require a central coordinator — the exact dependency federation must survive. Everything below holds unchanged within a namespace, which is where all current work sits.

+
  • A workplan prefix is owned by exactly one repository. No two repositories may use the same prefix.
  • A running number is never reused within a prefix, including after a workplan is cancelled, archived, or deleted. Numbers are allocated forward only.
  • Prefixes are derived from the project or repository identity, never from a flavor marker or category (PRJ-WP- is invalid by construction).
+

2. Hub identifiers stored in repository files must be derivable, not database-local. The defect is structural: a database-local key is stored in a shared artifact, so each database overwrites the other's value on every sync. It also inverts ADR-001 — a file carrying a hub's private key is the file holding hub state.

+

Target state (C2). state_hub_workstream_id and state_hub_task_id become deterministic: UUIDv5 derived from the workplan identifier. Per ADR-011 decision 3 the derivation input is the pair (namespace, identifier), not the identifier alone — deriving from the identifier alone would make two forks holding unrelated work under the same number compute the same UUID. Every instance computes the same value independently, writeback becomes idempotent, and any number of hub instances may coexist without coordination. The field shape is unchanged, so consumers keep working; only the provenance of the value changes.

+

This has a hard prerequisite: deterministic derivation from a non-unique identifier would manufacture collisions rather than remove them. Two project repos sharing PRJ-WP- would compute the same UUID for different workplans. Decision 1 must therefore be enforced before derivation ships.

+

Interim state (A). Until derivation lands, exactly one instance writes hub identifiers into repository files. Other instances may read, project, and serve, but must not mint workplan or task UUIDs into git-tracked files.

+

Corrected 2026-08-17, superseded by ADR-010 decisions 1–3. This decision originally described workstation hubs as "development read replicas". That was wrong on both counts: the workstation instance was not a replica, and it was the larger of the two, holding 306 more workplans than the primary. The two instances were peer databases. ADR-010 establishes the central hub as authoritative and local instances as rebuildable caches, which is what makes this interim rule coherent.

+

The interim is policy, enforced by discipline, and it has a real cost: registration requires connectivity to the registrar, so disconnected work cannot register. That cost is accepted only until C2 removes the need for it, at which point the number of hub instances becomes an availability choice rather than a correctness constraint.

+

Rejected. Collapsing to a single shared database (workstation hubs pointing at the production database) would also make identifiers consistent by construction, but it eliminates offline capability — cutting directly against STATE-WP-0068 (offline write buffer and edge relay) — and couples all local work to tunnel availability.

+

Ownership. Both the interim guard and the derivation belong to repo-manager under decision 747011c6, which already places file-backed record indexing and reconciliation there. Building either in state-hub would invest in a component being retired under STATE-WP-0079.

+

Migration scope for C2: 758 workplan files across the fleet currently carry these fields.

+

3. Lifecycle status is not automatically promoted. An automated normalization pass may report drift; it may not move a workplan from proposed to active. proposed means awaiting human review, and an automation that promotes it destroys the meaning of the review gate.

+

4. Repository manipulation is performed by a worker agent in that repository. This is the default topology.

+
  • A worker acting in repo X owns changes to repo X.
  • Multiple independent top-level workers inside a single repository are an exception, requiring an explicit reason, not a routine mode of operation.
  • Concurrent independent writers are what turned a two-registrar bug into repeated git divergence.
+

5. Project (prj-) repositories may act across their participating repositories. When work is governed by a project repo, its tasks may direct changes across every repository the project names, through the project's work agent, where that is more efficient than delegating.

+

This is a deliberate, scoped exception to decision 4: the project repo already owns cross-repo sequencing and its SCOPE.md names its participants, so its authority is declared rather than ad hoc. It does not license a worker in an arbitrary repository to reach into others.

+
+

Consequences

+

Positive. Workplan identifiers become citable without qualification. Hub IDs stop flip-flopping in git. The proposed status regains meaning. Cross-repo authority becomes something a repository declares rather than something any session assumes.

+

Negative. Existing collisions must be remediated (see below), which is disruptive. Workstation sessions lose the ability to register workplans directly and must route through the registrar or a worker in the owning repo. Prefix allocation needs a fleet-level registry, which is new machinery.

+

Enforcement. Prefix ownership, uniqueness, and forward-only numbering are repository standards, so they belong to Repo Manager under decision 747011c6 (RMGR-WP-0004), not to a hub. Canon defines the rule; Repo Manager checks it.

+
+

Migration — needs a separate ruling

+

Three prefixes and five identifiers are already colliding. Remediation options, in increasing cost:

+
  1. Freeze and forward-fix. Accept existing collisions as historical, enforce uniqueness only for new workplans. Cheapest; leaves RAILIANCE-WP-0015 permanently ambiguous.
  2. Renumber the live collisions only. Fix identifiers that are still cited or active; leave finished/archived duplicates alone.
  3. Full renaming. Give railiance-apps, railiance-forge, railiance-platform, railiance-telemetry distinct prefixes, likewise railiance-bootstrap/railiance-cluster and state-hub's legacy CUST-WP- files. Touches six repositories and every inbound reference.
+

Ruled 2026-08-17: option 2. Renumber live collisions; leave finished/archived duplicates as historical record.

+

The live renumber list is empty

+

Verified against the fleet scan. All five duplicated identifiers are finished:

+
CUST-WP-0000       the-custodian ×2      finished
+CUST-WP-0010       the-custodian ×2      finished
+CUST-WP-0045       the-custodian ×2      finished
+RAILIANCE-WP-0015  apps, platform        finished
+RAILIANCE-WP-0016  apps, platform ×2     finished
+

No workplan in a proposed, ready, active, blocked, or backlog state shares an identifier with another. Option 2 therefore requires no renumbering today. Historical duplicates stay, including the RAILIANCE-WP-0015 ambiguity between railiance-apps and railiance-platform; citations of it must name the repository.

+

The structural cause is not historical

+

Option 2 governs remediation. It does not exempt anything from decision 1, which is accepted canon: one prefix, one repository, forward-only numbering.

+

Three shared prefixes are still in use across seven repositories, and each is a single number line being allocated from concurrently:

+
RAIL-BS-WP-    bootstrap  8, 9
+               cluster    7, 10, 11, 12, 13, 14
+
+RAILIANCE-WP-  platform   5, 8-17 (16 twice — an internal duplicate)
+               apps       15, 16          <- already collided with platform
+               forge      2
+               telemetry  1
+
+CUST-WP-       the-custodian  50 plans
+               state-hub       4 legacy plans (canonical prefix is STATE-WP)
+

RAIL-BS- and RAILIANCE- are actively growing — RAIL-BS-WP-0014 (ready), RAILIANCE-WP-0002 (ready), RAILIANCE-WP-0001 (proposed), all created 2026-08-11 or later. The RAILIANCE-WP-0015/0016 collisions were not a historical accident; they are what concurrent allocation from a shared sequence produces, and it will recur at the next concurrent allocation.

+

CUST- is dormant on the state-hub side — four legacy plans, one in backlog — and needs no split, only a prefix-ownership assertion.

+

Prefix assignments

+

RAIL-BS-WP- is retired (2026-08-17). Neither repository keeps it: railiance-cluster adopts RCLUSTER-WP- for active and future plans; railiance-bootstrap adopts RBS-WP- for future plans. Finished and archived files keep RAIL-BS-WP- as historical record, consistent with option 2.

+

Migrating plans keep their running numbers — the prefix changes, the number does not. This preserves traceability and cannot violate forward-only allocation, because neither new prefix has prior history. railiance-bootstrap begins at RBS-WP-0010, above its historical maximum, leaving the lower range free should its finished plans ever be adopted into the new prefix.

+

RAILIANCE-WP- should follow the same pattern — retired rather than awarded to one repository, since it names a family rather than a repository and so fails decision 1 for the same reason PRJ-WP- does. Assignment of the four successor prefixes is outstanding.

+

Execution of each rename belongs to a worker in the owning repository under decision 4. RMGR-WP-0004-T09 records assignments and the numbering rule; it does not perform renames.

+

Consequence. Prefix ownership must be assigned for all three shared prefixes before the next workplan is created in the affected repositories. This is forward conformance under decision 1, not migration, and is tracked as RMGR-WP-0004-T09. Renaming the historical files is explicitly not required — that would be option 3, which was rejected.

+
+

References

+
  • Decision 747011c6 — repository standards belong to Repo Manager
  • ADR-001 — workplans originate as repo files; hub is a read model
  • RMGR-WP-0004 — repository standards conformance and governed scaffolding
  • STATE-WP-0080 — register scaffolding handoff
  • Fleet scan 2026-08-16: 955 hub workplans, 525 parseable identifiers, 3 reused prefixes, 5 reused identifiers
+
CUST-ADR-007 · accepted-1 · acceptedthe-custodian · canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb
diff --git a/build/adr/custodian-workplan-identity/v1/revisions/accepted-1/index.html b/build/adr/custodian-workplan-identity/v1/revisions/accepted-1/index.html new file mode 100644 index 0000000..9bc4cef --- /dev/null +++ b/build/adr/custodian-workplan-identity/v1/revisions/accepted-1/index.html @@ -0,0 +1,278 @@ + + + + +Workplan Identity Uniqueness, Single Registrar, and Repo Worker Topology + +
CUST-ADR-007 accepted · accepted-1 the-custodian reviewed 2026-08-17generated from canonical source — do not edit

Workplan Identity Uniqueness, Single Registrar, and Repo Worker Topology

Source: the-custodian · canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb

Review due: 2027-02-17

Status

+

Accepted 2026-08-17. Identifier uniqueness, the registrar model, lifecycle protection, and worker topology are settled.

+

Remediation of existing collisions (§ Migration) remains an open ruling. It is disruptive, touches six repositories, and no active work depends on it — all five duplicated identifiers are finished.

+
+

Context

+

On 2026-08-16, STATE-WP-0080 was found registered twice, in two different databases, with two different workplan UUIDs and two disjoint sets of task UUIDs:

+
RegistrarWorkplan UUIDReachable at 127.0.0.1:8000
Workstation hub (make api, local postgres)03f38314yes
A second instance, over a second databasebbfce36a404
+

The second instance is not identifiable from the commit author. custodian-sync@railiance.local is a hardcoded default git identity in scripts/consistency_check.py:1899 (GIT_SYNC_USER_NAME / GIT_SYNC_USER_EMAIL), so every machine running fix-consistency commits under that name. The discriminator is the timezone: sync commits appear under both +0000 and +0200 (the workstation's offset), which is independent evidence of two machines writing to one repository.

+

Both write their IDs into the same git-tracked workplan file, so each sync overwrites the other's IDs and the file flip-flops on every round trip. The same commit (ff909e1, "renormalize lifecycle state [auto]") also promoted the workplan proposed → active without human review.

+

A fleet scan of 955 hub workplans (525 with parseable PREFIX-WP-NNNN identifiers) found this is not an isolated incident. Two distinct identity defects are live:

+

Prefix reuse across repositories:

+
CUST-WP-      → state-hub, the-custodian
+RAIL-BS-WP-   → railiance-bootstrap, railiance-cluster
+RAILIANCE-WP- → railiance-apps, railiance-forge, railiance-platform, railiance-telemetry
+

PRJ-WP- is a latent fourth: statehub register derives it from the prj- flavor marker, so every project repository would collide (see RMGR-WP-0004).

+

Running-number reuse:

+
CUST-WP-0000       the-custodian ×2
+CUST-WP-0010       the-custodian ×2
+CUST-WP-0045       the-custodian ×2
+RAILIANCE-WP-0015  railiance-platform, railiance-apps
+RAILIANCE-WP-0016  railiance-platform ×2, railiance-apps
+

RAILIANCE-WP-0015 is actively cited in operational memory as the cnpg-backup gate in railiance-apps; a second record of the same name in railiance-platform makes that citation ambiguous.

+

The C-26 consistency check already flags prefix nonconformance within a repo against a canonical prefix, but nothing enforces uniqueness across repos, and nothing prevents number reuse.

+
+

Decision

+

1. A workplan identifier is globally unique. PREFIX-WP-NNNN names exactly one workplan across the entire fleet, for all time.

+

Amended 2026-08-17 by ADR-011 decision 2. Uniqueness and forward-only allocation are namespace-scoped, not global; global identity is the pair (namespace, identifier), written PREFIX-WP-NNNN@namespace when foreign. Global sequential allocation would require a central coordinator — the exact dependency federation must survive. Everything below holds unchanged within a namespace, which is where all current work sits.

+
  • A workplan prefix is owned by exactly one repository. No two repositories may use the same prefix.
  • A running number is never reused within a prefix, including after a workplan is cancelled, archived, or deleted. Numbers are allocated forward only.
  • Prefixes are derived from the project or repository identity, never from a flavor marker or category (PRJ-WP- is invalid by construction).
+

2. Hub identifiers stored in repository files must be derivable, not database-local. The defect is structural: a database-local key is stored in a shared artifact, so each database overwrites the other's value on every sync. It also inverts ADR-001 — a file carrying a hub's private key is the file holding hub state.

+

Target state (C2). state_hub_workstream_id and state_hub_task_id become deterministic: UUIDv5 derived from the workplan identifier. Per ADR-011 decision 3 the derivation input is the pair (namespace, identifier), not the identifier alone — deriving from the identifier alone would make two forks holding unrelated work under the same number compute the same UUID. Every instance computes the same value independently, writeback becomes idempotent, and any number of hub instances may coexist without coordination. The field shape is unchanged, so consumers keep working; only the provenance of the value changes.

+

This has a hard prerequisite: deterministic derivation from a non-unique identifier would manufacture collisions rather than remove them. Two project repos sharing PRJ-WP- would compute the same UUID for different workplans. Decision 1 must therefore be enforced before derivation ships.

+

Interim state (A). Until derivation lands, exactly one instance writes hub identifiers into repository files. Other instances may read, project, and serve, but must not mint workplan or task UUIDs into git-tracked files.

+

Corrected 2026-08-17, superseded by ADR-010 decisions 1–3. This decision originally described workstation hubs as "development read replicas". That was wrong on both counts: the workstation instance was not a replica, and it was the larger of the two, holding 306 more workplans than the primary. The two instances were peer databases. ADR-010 establishes the central hub as authoritative and local instances as rebuildable caches, which is what makes this interim rule coherent.

+

The interim is policy, enforced by discipline, and it has a real cost: registration requires connectivity to the registrar, so disconnected work cannot register. That cost is accepted only until C2 removes the need for it, at which point the number of hub instances becomes an availability choice rather than a correctness constraint.

+

Rejected. Collapsing to a single shared database (workstation hubs pointing at the production database) would also make identifiers consistent by construction, but it eliminates offline capability — cutting directly against STATE-WP-0068 (offline write buffer and edge relay) — and couples all local work to tunnel availability.

+

Ownership. Both the interim guard and the derivation belong to repo-manager under decision 747011c6, which already places file-backed record indexing and reconciliation there. Building either in state-hub would invest in a component being retired under STATE-WP-0079.

+

Migration scope for C2: 758 workplan files across the fleet currently carry these fields.

+

3. Lifecycle status is not automatically promoted. An automated normalization pass may report drift; it may not move a workplan from proposed to active. proposed means awaiting human review, and an automation that promotes it destroys the meaning of the review gate.

+

4. Repository manipulation is performed by a worker agent in that repository. This is the default topology.

+
  • A worker acting in repo X owns changes to repo X.
  • Multiple independent top-level workers inside a single repository are an exception, requiring an explicit reason, not a routine mode of operation.
  • Concurrent independent writers are what turned a two-registrar bug into repeated git divergence.
+

5. Project (prj-) repositories may act across their participating repositories. When work is governed by a project repo, its tasks may direct changes across every repository the project names, through the project's work agent, where that is more efficient than delegating.

+

This is a deliberate, scoped exception to decision 4: the project repo already owns cross-repo sequencing and its SCOPE.md names its participants, so its authority is declared rather than ad hoc. It does not license a worker in an arbitrary repository to reach into others.

+
+

Consequences

+

Positive. Workplan identifiers become citable without qualification. Hub IDs stop flip-flopping in git. The proposed status regains meaning. Cross-repo authority becomes something a repository declares rather than something any session assumes.

+

Negative. Existing collisions must be remediated (see below), which is disruptive. Workstation sessions lose the ability to register workplans directly and must route through the registrar or a worker in the owning repo. Prefix allocation needs a fleet-level registry, which is new machinery.

+

Enforcement. Prefix ownership, uniqueness, and forward-only numbering are repository standards, so they belong to Repo Manager under decision 747011c6 (RMGR-WP-0004), not to a hub. Canon defines the rule; Repo Manager checks it.

+
+

Migration — needs a separate ruling

+

Three prefixes and five identifiers are already colliding. Remediation options, in increasing cost:

+
  1. Freeze and forward-fix. Accept existing collisions as historical, enforce uniqueness only for new workplans. Cheapest; leaves RAILIANCE-WP-0015 permanently ambiguous.
  2. Renumber the live collisions only. Fix identifiers that are still cited or active; leave finished/archived duplicates alone.
  3. Full renaming. Give railiance-apps, railiance-forge, railiance-platform, railiance-telemetry distinct prefixes, likewise railiance-bootstrap/railiance-cluster and state-hub's legacy CUST-WP- files. Touches six repositories and every inbound reference.
+

Ruled 2026-08-17: option 2. Renumber live collisions; leave finished/archived duplicates as historical record.

+

The live renumber list is empty

+

Verified against the fleet scan. All five duplicated identifiers are finished:

+
CUST-WP-0000       the-custodian ×2      finished
+CUST-WP-0010       the-custodian ×2      finished
+CUST-WP-0045       the-custodian ×2      finished
+RAILIANCE-WP-0015  apps, platform        finished
+RAILIANCE-WP-0016  apps, platform ×2     finished
+

No workplan in a proposed, ready, active, blocked, or backlog state shares an identifier with another. Option 2 therefore requires no renumbering today. Historical duplicates stay, including the RAILIANCE-WP-0015 ambiguity between railiance-apps and railiance-platform; citations of it must name the repository.

+

The structural cause is not historical

+

Option 2 governs remediation. It does not exempt anything from decision 1, which is accepted canon: one prefix, one repository, forward-only numbering.

+

Three shared prefixes are still in use across seven repositories, and each is a single number line being allocated from concurrently:

+
RAIL-BS-WP-    bootstrap  8, 9
+               cluster    7, 10, 11, 12, 13, 14
+
+RAILIANCE-WP-  platform   5, 8-17 (16 twice — an internal duplicate)
+               apps       15, 16          <- already collided with platform
+               forge      2
+               telemetry  1
+
+CUST-WP-       the-custodian  50 plans
+               state-hub       4 legacy plans (canonical prefix is STATE-WP)
+

RAIL-BS- and RAILIANCE- are actively growing — RAIL-BS-WP-0014 (ready), RAILIANCE-WP-0002 (ready), RAILIANCE-WP-0001 (proposed), all created 2026-08-11 or later. The RAILIANCE-WP-0015/0016 collisions were not a historical accident; they are what concurrent allocation from a shared sequence produces, and it will recur at the next concurrent allocation.

+

CUST- is dormant on the state-hub side — four legacy plans, one in backlog — and needs no split, only a prefix-ownership assertion.

+

Prefix assignments

+

RAIL-BS-WP- is retired (2026-08-17). Neither repository keeps it: railiance-cluster adopts RCLUSTER-WP- for active and future plans; railiance-bootstrap adopts RBS-WP- for future plans. Finished and archived files keep RAIL-BS-WP- as historical record, consistent with option 2.

+

Migrating plans keep their running numbers — the prefix changes, the number does not. This preserves traceability and cannot violate forward-only allocation, because neither new prefix has prior history. railiance-bootstrap begins at RBS-WP-0010, above its historical maximum, leaving the lower range free should its finished plans ever be adopted into the new prefix.

+

RAILIANCE-WP- should follow the same pattern — retired rather than awarded to one repository, since it names a family rather than a repository and so fails decision 1 for the same reason PRJ-WP- does. Assignment of the four successor prefixes is outstanding.

+

Execution of each rename belongs to a worker in the owning repository under decision 4. RMGR-WP-0004-T09 records assignments and the numbering rule; it does not perform renames.

+

Consequence. Prefix ownership must be assigned for all three shared prefixes before the next workplan is created in the affected repositories. This is forward conformance under decision 1, not migration, and is tracked as RMGR-WP-0004-T09. Renaming the historical files is explicitly not required — that would be option 3, which was rejected.

+
+

References

+
  • Decision 747011c6 — repository standards belong to Repo Manager
  • ADR-001 — workplans originate as repo files; hub is a read model
  • RMGR-WP-0004 — repository standards conformance and governed scaffolding
  • STATE-WP-0080 — register scaffolding handoff
  • Fleet scan 2026-08-16: 955 hub workplans, 525 parseable identifiers, 3 reused prefixes, 5 reused identifiers
+
CUST-ADR-007 · accepted-1 · acceptedthe-custodian · canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb
diff --git a/build/adr/custodian-workplans-as-repo-artefacts/v1/index.html b/build/adr/custodian-workplans-as-repo-artefacts/v1/index.html new file mode 100644 index 0000000..779cedd --- /dev/null +++ b/build/adr/custodian-workplans-as-repo-artefacts/v1/index.html @@ -0,0 +1,298 @@ + + + + +Workplans and Work Items Are Repository Artefacts + +
CUST-ADR-001 accepted · accepted-1 the-custodian reviewed 2026-02-28generated from canonical source — do not edit

Workplans and Work Items Are Repository Artefacts

Source: the-custodian · canon/architecture/adr-001-workplans-as-repo-artefacts.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb

Review due: 2026-08-28

Status

+

Accepted.

+
+

Context

+

During early State Hub development (v0.1–v0.4), workstreams and tasks were created directly in the PostgreSQL database via MCP bootstrap tools (create_workstream, create_task). This made the database the origin of work items — not a cache or index. The pattern was convenient for rapid bootstrapping but is architecturally wrong for a system built on the values of auditability, reversibility, and local-first sovereignty.

+

The trigger for formalising this decision was the creation of the v0.5 workplan ("Dynamic Domains & Multi-Repo") directly in the state-hub database without a corresponding file artefact in any repository.

+
+

Decision

+

Workplans and work items MUST originate as Markdown files in the repository that owns them. The Custodian State Hub indexes and caches those artefacts but is never their origin.

+

Formally: the state-hub must (theoretically, given sufficient compute and time) be able to rebuild its full representation of repositories, their workplans, tasks, decisions, and dependencies by reading only the files in the registered repositories. No information that matters for coordination should exist solely in the database.

+

Corollaries

+
  1. Repository is authoritative. A workplan file is the canonical record. The state-hub database row is a materialized cache of that file.
+
  1. Database is disposable. Dropping and re-creating the database from registered repository files must produce an equivalent state. The database is an operational convenience, not a primary store.
+
  1. MCP bootstrap tools become index/sync tools. create_workstream and create_task are acceptable as convenience wrappers only if they write the file first and then register the row. Using them to write DB-only records violates this ADR.
+
  1. The rebuild principle implies a sync mechanism. There must be a defined path (make sync-workplans or equivalent) by which the state-hub reads workplan files from registered repositories and upserts its database state.
+
+

Workplan File Convention

+

Each workplan lives in a workplans/ directory in the repository that owns the work. The owning repository is identified by domain.

+

Location

+
<repo-root>/workplans/<id>-<slug>.md
+

Examples:

+
  • the-custodian/workplans/CUST-WP-0005-dynamic-domains.md
  • railiance/workplans/RAIL-WP-0001-three-phoenix.md
+

Frontmatter Schema

+
---
+id: CUST-WP-0005            # human-readable workplan ID, unique per repo
+type: workplan
+title: "State Hub v0.5 — Dynamic Domains & Multi-Repo"
+domain: custodian            # must match a registered domain slug
+status: active               # active | completed | archived
+owner: custodian
+topic_slug: custodian        # maps to a state-hub Topic slug
+created: "2026-02-28"
+updated: "2026-02-28"
+---
+

Task Items

+

Tasks are embedded in the workplan file as headed sections. Each task section carries its own YAML block:

+
## P1.1 — Create `domains` table + Alembic migration
+
+

id: CUST-WP-0005-T001 status: todo priority: high

+
+Task description prose here.
+

The state-hub parses these embedded task blocks during ingestion and upserts rows in the tasks table. The id field is the stable external key; the state-hub UUID is internal and opaque.

+

Decision Items

+

Decisions are separate files or embedded sections following the same pattern, using type: decision in frontmatter.

+
+

Rebuild Principle

+

The rebuild sequence for a clean state-hub:

+
  1. make migrate — create schema
  2. make seed-domains — insert domain rows (domains.yaml in canon/)
  3. For each registered repository: make sync-workplans REPO=<slug> — parse workplan files and upsert workstreams, tasks, decisions
  4. make sync-progress — replay progress events from episodic memory logs
+

After step 4 the database must be functionally equivalent to the live state.

+
+

Consequences

+

Immediate

+
  • The v0.5 and v0.3 workplans created DB-first in this session are legacy records that violate this ADR. Remediation: write the corresponding workplan files, then mark the DB rows as source: db-legacy until a sync mechanism can reconcile them.
+
  • The state-hub CLAUDE.md design-boundary note must be updated: the MCP bootstrap tools are permitted only as write-through tools (file + DB), never as DB-only tools.
+

Medium Term

+
  • A make sync-workplans command must be implemented as part of the managed-repos / contribution-tracking infrastructure (see v0.3 workplan).
+
  • The managed_repos table is the prerequisite: the state-hub must know which repositories to scan.
+
  • Workplan file format must be versioned and parsed by a dedicated loader (state-hub/scripts/sync_workplans.py).
+

Long Term

+
  • When the state-hub grows to cover multiple users or teams, this principle ensures that no coordination state can be lost by a database failure. Every repository is its own resilient shard of the coordination graph.
+
  • This is the foundation for the "transgenerational" property: workplans in git survive database migrations, cloud provider changes, and system rebuilds.
+
+

Alternatives Considered

+

Database-first with export: Create in DB, export to files on demand. Rejected: export is easily skipped and files become secondary/stale.

+

Files-only, no database: Parse files on every query. Rejected: impractical at scale; the database is a necessary cache for cross-repo aggregation and real-time dashboard queries.

+

Hybrid with explicit sync flag: Mark some records as "db-authoritative" and others as "file-authoritative." Rejected: introduces ambiguity about which records matter; violates the "single source of truth" principle.

+
+

Workplan Closure Protocol

+

When a workplan is about to be marked finished, the responsible agent MUST perform a closure review before writing the status change. This prevents the stale-task accumulation that this ADR was designed to make detectable.

+

Steps

+
  1. Query all non-done tasks in the workplan via GET /tasks/?workplan_id=<uuid> (legacy alias: workstream_id; filter for todo, in_progress, blocked).
+
  1. Classify each task into one of three outcomes:
+
OutcomeAction
Done — work was completed, DB record just wasn't updatedPATCH /tasks/{id}/ {"status": "done"}
Cancelled — dropped, superseded, or out of scopePATCH /tasks/{id}/ {"status": "cancelled", "blocking_reason": "<why>"}
Carry-forward — genuinely unfinished, belongs in the next runLeave open; note in closure review; trigger new workplan
+
  1. Append a ## Closure Review section to the workplan file:
+
   ## Closure Review — YYYY-MM-DD
+
+   **Outcome:** All tasks completed / N tasks carried forward / N tasks dropped.
+
+   ### Completed (DB updated)
+   - TASK-ID — title
+
+   ### Cancelled (dropped)
+   | Task | Reason |
+   |------|--------|
+   | TASK-ID — title | Superseded by X |
+
+   ### Carried forward
+   | Task | Target workplan |
+   |------|----------------|
+   | TASK-ID — title | CUST-WP-XXXX |
+
  1. If any tasks are carried forward: do not mark the workplan finished yet. Create the new workplan file (or amend an existing active one), then close the current workplan.
+
  1. Update the workplan frontmatter status: finished and updated: date.
+
  1. Mark the workplan finished in the state hub via MCP or API (update_workplan_status).
+

Daily Stale-Task Cleanup

+

As a safety net for cases where the closure review was skipped or incomplete, a cleanup script cancels any surviving open tasks in completed/archived workstreams:

+
cd ~/the-custodian/state-hub
+make cleanup-stale            # run immediately
+# or add to cron:
+# 0 3 * * * cd ~/the-custodian/state-hub && make cleanup-stale
+

The script (scripts/cleanup_stale_tasks.py) emits a cleanup progress event recording which tasks were cancelled and in which workstreams. Tasks cancelled by the cleanup carry a blocking_reason noting they should be verified against the workplan file.

+

The closure review is the primary mechanism; the cleanup is the fallback. If the cleanup regularly cancels tasks, it signals that closure reviews are being skipped — that is the process failure to address, not just the stale tasks.

+
+
CUST-ADR-001 · accepted-1 · acceptedthe-custodian · canon/architecture/adr-001-workplans-as-repo-artefacts.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb
diff --git a/build/adr/custodian-workplans-as-repo-artefacts/v1/revisions/accepted-1/index.html b/build/adr/custodian-workplans-as-repo-artefacts/v1/revisions/accepted-1/index.html new file mode 100644 index 0000000..779cedd --- /dev/null +++ b/build/adr/custodian-workplans-as-repo-artefacts/v1/revisions/accepted-1/index.html @@ -0,0 +1,298 @@ + + + + +Workplans and Work Items Are Repository Artefacts + +
CUST-ADR-001 accepted · accepted-1 the-custodian reviewed 2026-02-28generated from canonical source — do not edit

Workplans and Work Items Are Repository Artefacts

Source: the-custodian · canon/architecture/adr-001-workplans-as-repo-artefacts.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb

Review due: 2026-08-28

Status

+

Accepted.

+
+

Context

+

During early State Hub development (v0.1–v0.4), workstreams and tasks were created directly in the PostgreSQL database via MCP bootstrap tools (create_workstream, create_task). This made the database the origin of work items — not a cache or index. The pattern was convenient for rapid bootstrapping but is architecturally wrong for a system built on the values of auditability, reversibility, and local-first sovereignty.

+

The trigger for formalising this decision was the creation of the v0.5 workplan ("Dynamic Domains & Multi-Repo") directly in the state-hub database without a corresponding file artefact in any repository.

+
+

Decision

+

Workplans and work items MUST originate as Markdown files in the repository that owns them. The Custodian State Hub indexes and caches those artefacts but is never their origin.

+

Formally: the state-hub must (theoretically, given sufficient compute and time) be able to rebuild its full representation of repositories, their workplans, tasks, decisions, and dependencies by reading only the files in the registered repositories. No information that matters for coordination should exist solely in the database.

+

Corollaries

+
  1. Repository is authoritative. A workplan file is the canonical record. The state-hub database row is a materialized cache of that file.
+
  1. Database is disposable. Dropping and re-creating the database from registered repository files must produce an equivalent state. The database is an operational convenience, not a primary store.
+
  1. MCP bootstrap tools become index/sync tools. create_workstream and create_task are acceptable as convenience wrappers only if they write the file first and then register the row. Using them to write DB-only records violates this ADR.
+
  1. The rebuild principle implies a sync mechanism. There must be a defined path (make sync-workplans or equivalent) by which the state-hub reads workplan files from registered repositories and upserts its database state.
+
+

Workplan File Convention

+

Each workplan lives in a workplans/ directory in the repository that owns the work. The owning repository is identified by domain.

+

Location

+
<repo-root>/workplans/<id>-<slug>.md
+

Examples:

+
  • the-custodian/workplans/CUST-WP-0005-dynamic-domains.md
  • railiance/workplans/RAIL-WP-0001-three-phoenix.md
+

Frontmatter Schema

+
---
+id: CUST-WP-0005            # human-readable workplan ID, unique per repo
+type: workplan
+title: "State Hub v0.5 — Dynamic Domains & Multi-Repo"
+domain: custodian            # must match a registered domain slug
+status: active               # active | completed | archived
+owner: custodian
+topic_slug: custodian        # maps to a state-hub Topic slug
+created: "2026-02-28"
+updated: "2026-02-28"
+---
+

Task Items

+

Tasks are embedded in the workplan file as headed sections. Each task section carries its own YAML block:

+
## P1.1 — Create `domains` table + Alembic migration
+
+

id: CUST-WP-0005-T001 status: todo priority: high

+
+Task description prose here.
+

The state-hub parses these embedded task blocks during ingestion and upserts rows in the tasks table. The id field is the stable external key; the state-hub UUID is internal and opaque.

+

Decision Items

+

Decisions are separate files or embedded sections following the same pattern, using type: decision in frontmatter.

+
+

Rebuild Principle

+

The rebuild sequence for a clean state-hub:

+
  1. make migrate — create schema
  2. make seed-domains — insert domain rows (domains.yaml in canon/)
  3. For each registered repository: make sync-workplans REPO=<slug> — parse workplan files and upsert workstreams, tasks, decisions
  4. make sync-progress — replay progress events from episodic memory logs
+

After step 4 the database must be functionally equivalent to the live state.

+
+

Consequences

+

Immediate

+
  • The v0.5 and v0.3 workplans created DB-first in this session are legacy records that violate this ADR. Remediation: write the corresponding workplan files, then mark the DB rows as source: db-legacy until a sync mechanism can reconcile them.
+
  • The state-hub CLAUDE.md design-boundary note must be updated: the MCP bootstrap tools are permitted only as write-through tools (file + DB), never as DB-only tools.
+

Medium Term

+
  • A make sync-workplans command must be implemented as part of the managed-repos / contribution-tracking infrastructure (see v0.3 workplan).
+
  • The managed_repos table is the prerequisite: the state-hub must know which repositories to scan.
+
  • Workplan file format must be versioned and parsed by a dedicated loader (state-hub/scripts/sync_workplans.py).
+

Long Term

+
  • When the state-hub grows to cover multiple users or teams, this principle ensures that no coordination state can be lost by a database failure. Every repository is its own resilient shard of the coordination graph.
+
  • This is the foundation for the "transgenerational" property: workplans in git survive database migrations, cloud provider changes, and system rebuilds.
+
+

Alternatives Considered

+

Database-first with export: Create in DB, export to files on demand. Rejected: export is easily skipped and files become secondary/stale.

+

Files-only, no database: Parse files on every query. Rejected: impractical at scale; the database is a necessary cache for cross-repo aggregation and real-time dashboard queries.

+

Hybrid with explicit sync flag: Mark some records as "db-authoritative" and others as "file-authoritative." Rejected: introduces ambiguity about which records matter; violates the "single source of truth" principle.

+
+

Workplan Closure Protocol

+

When a workplan is about to be marked finished, the responsible agent MUST perform a closure review before writing the status change. This prevents the stale-task accumulation that this ADR was designed to make detectable.

+

Steps

+
  1. Query all non-done tasks in the workplan via GET /tasks/?workplan_id=<uuid> (legacy alias: workstream_id; filter for todo, in_progress, blocked).
+
  1. Classify each task into one of three outcomes:
+
OutcomeAction
Done — work was completed, DB record just wasn't updatedPATCH /tasks/{id}/ {"status": "done"}
Cancelled — dropped, superseded, or out of scopePATCH /tasks/{id}/ {"status": "cancelled", "blocking_reason": "<why>"}
Carry-forward — genuinely unfinished, belongs in the next runLeave open; note in closure review; trigger new workplan
+
  1. Append a ## Closure Review section to the workplan file:
+
   ## Closure Review — YYYY-MM-DD
+
+   **Outcome:** All tasks completed / N tasks carried forward / N tasks dropped.
+
+   ### Completed (DB updated)
+   - TASK-ID — title
+
+   ### Cancelled (dropped)
+   | Task | Reason |
+   |------|--------|
+   | TASK-ID — title | Superseded by X |
+
+   ### Carried forward
+   | Task | Target workplan |
+   |------|----------------|
+   | TASK-ID — title | CUST-WP-XXXX |
+
  1. If any tasks are carried forward: do not mark the workplan finished yet. Create the new workplan file (or amend an existing active one), then close the current workplan.
+
  1. Update the workplan frontmatter status: finished and updated: date.
+
  1. Mark the workplan finished in the state hub via MCP or API (update_workplan_status).
+

Daily Stale-Task Cleanup

+

As a safety net for cases where the closure review was skipped or incomplete, a cleanup script cancels any surviving open tasks in completed/archived workstreams:

+
cd ~/the-custodian/state-hub
+make cleanup-stale            # run immediately
+# or add to cron:
+# 0 3 * * * cd ~/the-custodian/state-hub && make cleanup-stale
+

The script (scripts/cleanup_stale_tasks.py) emits a cleanup progress event recording which tasks were cancelled and in which workstreams. Tasks cancelled by the cleanup carry a blocking_reason noting they should be verified against the workplan file.

+

The closure review is the primary mechanism; the cleanup is the fallback. If the cleanup regularly cancels tasks, it signals that closure reviews are being skipped — that is the process failure to address, not just the stale tasks.

+
+
CUST-ADR-001 · accepted-1 · acceptedthe-custodian · canon/architecture/adr-001-workplans-as-repo-artefacts.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb
diff --git a/build/adr/railiance-decisions-live-in-the-repo/v1/index.html b/build/adr/railiance-decisions-live-in-the-repo/v1/index.html new file mode 100644 index 0000000..10a9696 --- /dev/null +++ b/build/adr/railiance-decisions-live-in-the-repo/v1/index.html @@ -0,0 +1,211 @@ + + + + +ADR-0003 — Decisions that bind others live in docs/adr, not only in the State Hub + +
RPLAT-ADR-0003 accepted · 1.0 railiance-platform reviewed 2026-08-17generated from canonical source — do not edit

ADR-0003 — Decisions that bind others live in docs/adr, not only in the State Hub

Source: railiance-platform · docs/adr/ADR-0003-decisions-live-in-the-repo.md · 56d516e10cdad6691f254ec9cb11f11ea364f7de

Review due: 2027-02-17

Context

+

This repo recorded decisions with the State Hub's record_decision() and wrote governing content as prose in docs/ — 24 files on 2026-08-17, none carrying a status, owner, revision or review date. It held no ADRs at all.

+

Two things made that a defect rather than a style.

+

The hub is a read model. The estate's standing rule is that local files are the source of truth and the hub reflects them. A decision that exists only as a hub record inverts that for the one class of content where it matters most.

+

policy-nexus publishes canon and ADRs only, globbing docs/adr/*.md from each repo. A repo with no ADRs is invisible to the estate's publication surface no matter how much governing content it holds. This repo owns S3 boundary rules, the credential-lane model and the consumption-mode gate — all binding on other repos, all unpublishable.

+

The gap was structural, not an oversight: nothing in the session protocol ever told anyone to write an ADR here.

+
+

Decision

+

A decision that binds anyone outside this repo is recorded as an ADR in docs/adr/, with the frontmatter in docs/adr/README.md, before or alongside any hub record. The hub record points at the ADR; it does not replace it.

+

Runbooks and procedures stay as prose in docs/ and stay unpublished. The test is not importance — several runbooks are critical — but whether the document decides something for someone else.

+
+

Consequences

+
  • docs/adr/ exists, with a convention, a template and this repo's first three ADRs.
  • Existing prose is not converted wholesale. Content is promoted when it is next touched, or when a consumer needs to cite it.
  • last_reviewed and review_interval are mandatory here, which is stricter than the estate norm — of 69 ADRs across 19 repos on 2026-08-17, 21 had YAML frontmatter and 2 had any notion of a review date. POLICY-NEXUS-WP-0001 T05 cannot compute staleness without those fields and must not invent them, since inventing them would make the publication a second source of truth, which is that workplan's own top risk. Routed as RPF-WP-0018 finding F5.
  • Session protocol guidance should follow, so the next agent writes an ADR without being told. Not done in this ADR.
+
+

Alternatives considered

+

Keep decisions in the hub and have policy-nexus read it. Rejected on both sides: it would make a read model authoritative, and it would give the publication surface a source that no repo can diff or review.

+

Add frontmatter to all 24 existing docs/ files. Rejected. Most are runbooks that should not be published, and stamping them with a status would assert a decision that was never made.

+
RPLAT-ADR-0003 · 1.0 · acceptedrailiance-platform · docs/adr/ADR-0003-decisions-live-in-the-repo.md · 56d516e10cdad6691f254ec9cb11f11ea364f7de
diff --git a/build/adr/railiance-decisions-live-in-the-repo/v1/revisions/1.0/index.html b/build/adr/railiance-decisions-live-in-the-repo/v1/revisions/1.0/index.html new file mode 100644 index 0000000..10a9696 --- /dev/null +++ b/build/adr/railiance-decisions-live-in-the-repo/v1/revisions/1.0/index.html @@ -0,0 +1,211 @@ + + + + +ADR-0003 — Decisions that bind others live in docs/adr, not only in the State Hub + +
RPLAT-ADR-0003 accepted · 1.0 railiance-platform reviewed 2026-08-17generated from canonical source — do not edit

ADR-0003 — Decisions that bind others live in docs/adr, not only in the State Hub

Source: railiance-platform · docs/adr/ADR-0003-decisions-live-in-the-repo.md · 56d516e10cdad6691f254ec9cb11f11ea364f7de

Review due: 2027-02-17

Context

+

This repo recorded decisions with the State Hub's record_decision() and wrote governing content as prose in docs/ — 24 files on 2026-08-17, none carrying a status, owner, revision or review date. It held no ADRs at all.

+

Two things made that a defect rather than a style.

+

The hub is a read model. The estate's standing rule is that local files are the source of truth and the hub reflects them. A decision that exists only as a hub record inverts that for the one class of content where it matters most.

+

policy-nexus publishes canon and ADRs only, globbing docs/adr/*.md from each repo. A repo with no ADRs is invisible to the estate's publication surface no matter how much governing content it holds. This repo owns S3 boundary rules, the credential-lane model and the consumption-mode gate — all binding on other repos, all unpublishable.

+

The gap was structural, not an oversight: nothing in the session protocol ever told anyone to write an ADR here.

+
+

Decision

+

A decision that binds anyone outside this repo is recorded as an ADR in docs/adr/, with the frontmatter in docs/adr/README.md, before or alongside any hub record. The hub record points at the ADR; it does not replace it.

+

Runbooks and procedures stay as prose in docs/ and stay unpublished. The test is not importance — several runbooks are critical — but whether the document decides something for someone else.

+
+

Consequences

+
  • docs/adr/ exists, with a convention, a template and this repo's first three ADRs.
  • Existing prose is not converted wholesale. Content is promoted when it is next touched, or when a consumer needs to cite it.
  • last_reviewed and review_interval are mandatory here, which is stricter than the estate norm — of 69 ADRs across 19 repos on 2026-08-17, 21 had YAML frontmatter and 2 had any notion of a review date. POLICY-NEXUS-WP-0001 T05 cannot compute staleness without those fields and must not invent them, since inventing them would make the publication a second source of truth, which is that workplan's own top risk. Routed as RPF-WP-0018 finding F5.
  • Session protocol guidance should follow, so the next agent writes an ADR without being told. Not done in this ADR.
+
+

Alternatives considered

+

Keep decisions in the hub and have policy-nexus read it. Rejected on both sides: it would make a read model authoritative, and it would give the publication surface a source that no repo can diff or review.

+

Add frontmatter to all 24 existing docs/ files. Rejected. Most are runbooks that should not be published, and stamping them with a status would assert a decision that was never made.

+
RPLAT-ADR-0003 · 1.0 · acceptedrailiance-platform · docs/adr/ADR-0003-decisions-live-in-the-repo.md · 56d516e10cdad6691f254ec9cb11f11ea364f7de
diff --git a/build/adr/railiance-derived-rail-composition/v1/index.html b/build/adr/railiance-derived-rail-composition/v1/index.html index 3a22536..c5649d8 100644 --- a/build/adr/railiance-derived-rail-composition/v1/index.html +++ b/build/adr/railiance-derived-rail-composition/v1/index.html @@ -1,6 +1,6 @@ - + Derived Rail Composition -
RMASTER-ADR-0005 accepted · accepted-1 railiance-master reviewed 2026-07-26generated from canonical source — do not edit

Derived Rail Composition

Source: railiance-master · docs/adr/ADR-0005-derived-rail-composition.md · 883533ed8af1703cc9bb4a2b24137e325bbbda47

Review due: 2027-01-26

Date: 2026-07-26 Status: Accepted

+
RMASTER-ADR-0005 accepted · accepted-1 railiance-master reviewed 2026-07-26generated from canonical source — do not edit

Derived Rail Composition

Source: railiance-master · docs/adr/ADR-0005-derived-rail-composition.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d

Review due: 2027-01-26

Date: 2026-07-26 Status: Accepted

Context

Knative provides distinct workload activation and revision semantics but runs on Kubernetes. Treating it as an unrelated peer rail would duplicate generic workload lifecycle and substrate assumptions.

@@ -202,4 +202,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

Consequences

  • New platform workloads continue to use rail-kubernetes unless a specialized rail is justified.
  • Derived rails declare base-rail compatibility rather than copying lifecycle contracts.
  • Fabric and conformance tooling must understand rail dependency and readiness.
  • Knative installation stays with the S2 substrate owner.
-
RMASTER-ADR-0005 · accepted-1 · acceptedrailiance-master · docs/adr/ADR-0005-derived-rail-composition.md · 883533ed8af1703cc9bb4a2b24137e325bbbda47
+
RMASTER-ADR-0005 · accepted-1 · acceptedrailiance-master · docs/adr/ADR-0005-derived-rail-composition.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d
diff --git a/build/adr/railiance-first-wave-reef-rollout/v1/index.html b/build/adr/railiance-first-wave-reef-rollout/v1/index.html index d0b58af..4dd6eda 100644 --- a/build/adr/railiance-first-wave-reef-rollout/v1/index.html +++ b/build/adr/railiance-first-wave-reef-rollout/v1/index.html @@ -1,6 +1,6 @@ - + First-Wave reef Rollout -
RMASTER-ADR-0004 accepted · accepted-1 railiance-master reviewed 2026-07-26generated from canonical source — do not edit

First-Wave reef Rollout

Source: railiance-master · docs/adr/ADR-0004-first-wave-reef-rollout.md · 883533ed8af1703cc9bb4a2b24137e325bbbda47

Review due: 2027-01-26

Date: 2026-07-25 Status: Accepted

+
RMASTER-ADR-0004 accepted · accepted-1 railiance-master reviewed 2026-07-26generated from canonical source — do not edit

First-Wave reef Rollout

Source: railiance-master · docs/adr/ADR-0004-first-wave-reef-rollout.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d

Review due: 2027-01-26

Date: 2026-07-25 Status: Accepted

Context

Railiance now has a reef model, but it needs a concrete first rollout.

The current substrate reality is not uniform:

@@ -214,4 +214,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

Notes

This ADR chooses the first rollout set. It does not require that every future substrate be modeled the same way.

-
RMASTER-ADR-0004 · accepted-1 · acceptedrailiance-master · docs/adr/ADR-0004-first-wave-reef-rollout.md · 883533ed8af1703cc9bb4a2b24137e325bbbda47
+
RMASTER-ADR-0004 · accepted-1 · acceptedrailiance-master · docs/adr/ADR-0004-first-wave-reef-rollout.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d
diff --git a/build/adr/railiance-placement-policy-ownership/v1/index.html b/build/adr/railiance-placement-policy-ownership/v1/index.html new file mode 100644 index 0000000..ffeebbb --- /dev/null +++ b/build/adr/railiance-placement-policy-ownership/v1/index.html @@ -0,0 +1,212 @@ + + + + +ADR-0002 — S3 owns the placement rule; the package repo owns the number + +
RPLAT-ADR-0002 proposed · 1.0 railiance-platform reviewed 2026-08-17generated from canonical source — do not edit

ADR-0002 — S3 owns the placement rule; the package repo owns the number

Source: railiance-platform · docs/adr/ADR-0002-placement-policy-ownership.md · 56d516e10cdad6691f254ec9cb11f11ea364f7de

Review due: 2027-02-17

Context

+

An earlier draft of net-kingdom/canon/standards/tenancy-posture_v0.1.md §8.2 proposed that database placement policy — dedicated versus shared, and when that changes — be owned by railiance-platform, co-signed by adaptive-pricing. tenant-engine raised the same gap independently on 2026-08-16: both patterns are live on railiance01, neither is written down, and each new service copies whichever neighbour it looked at.

+

The complication is that this repo no longer holds the specs. RAILIANCE-WP-0012 and RAILIANCE-WP-0015 moved the deployable surface to the rapp-* repos. platform-pg's instances, max_connections, memory limit and retention are rapp-postgres's cluster CR. Tenancy Posture §19.8 nonetheless asks this repo for platform-pg's declared maximum size — a question one hop from where its answer lives.

+

Accepting ownership without stating this would produce either an answer we cannot substantiate or a quiet non-answer.

+
+

Decision

+

Accept placement ownership, split along rule and number.

+

This repo owns the rule: the default placement level, what overrides it, who is accountable for each workload's placement, that a shared cluster must publish a ceiling and an overflow target before its third consumer, that retention has a floor and a ceiling, and that a consumer's erasure horizon on shared substrate is disclosed rather than inherited silently.

+

The package repo owns the number: what the ceiling actually is, which resource binds first, what the retention values are, and the validator that enforces them where the CR lives.

+

Placement ownership per workload sits with the consuming repo; this repo co-signs. The consumer knows its latency requirement, erasure horizon and compliance position; S3 knows the substrate. A placement change needs both. Putting the decision solely here would recreate the problem §8.2 exists to avoid — an operations-shaped repo holding a commercial decision alone.

+

adaptive-pricing declined the standing co-signature on 2026-08-17. The replacement is binding and machine-reconcilable: it publishes typed tier minimums; this policy validates placement against them. Ownership stays here.

+
+

Consequences

+
  • docs/placement-policy.md is the operative document; this ADR is the decision behind it.
  • §19.8 is answered for platform-pg by rapp-postgres ADR-0004: four consumers, with platform-pg-2 named as the still-absent overflow target. Rule P-4.1 still requires apps-pg to declare its own ceiling before its third consumer.
  • This repo owes apps-pg's ceiling under its own rule. A policy whose author is exempt is not a policy.
  • §8.1 requires triggers to be monitored. This repo has no monitoring plane, so the connection-and-memory-ceiling trigger is recorded unmonitored pending railiance-telemetry. Declaring a ceiling is a partial substitute — a written threshold is checkable by a human at provisioning, which beats a limit discovered by an OOM kill.
  • adaptive-pricing's decline is recorded as single policy ownership plus a mandatory typed constraint join, not as an absent signature.
+
+

Alternatives considered

+

Decline ownership; route it to rapp-postgres. They hold the specs and the operational knowledge. Rejected: placement is a cross-cluster question and rapp-postgres owns one package. A policy owned by one substrate's operator cannot govern movement between substrates.

+

Accept whole, including the numbers. Rejected: it would either re-import the deployable surface this repo deliberately gave up, or produce numbers restated here that drift from the CR — a second source of truth for exactly the values a consumer must be able to trust.

+
RPLAT-ADR-0002 · 1.0 · proposedrailiance-platform · docs/adr/ADR-0002-placement-policy-ownership.md · 56d516e10cdad6691f254ec9cb11f11ea364f7de
diff --git a/build/adr/railiance-placement-policy-ownership/v1/revisions/1.0/index.html b/build/adr/railiance-placement-policy-ownership/v1/revisions/1.0/index.html new file mode 100644 index 0000000..ffeebbb --- /dev/null +++ b/build/adr/railiance-placement-policy-ownership/v1/revisions/1.0/index.html @@ -0,0 +1,212 @@ + + + + +ADR-0002 — S3 owns the placement rule; the package repo owns the number + +
RPLAT-ADR-0002 proposed · 1.0 railiance-platform reviewed 2026-08-17generated from canonical source — do not edit

ADR-0002 — S3 owns the placement rule; the package repo owns the number

Source: railiance-platform · docs/adr/ADR-0002-placement-policy-ownership.md · 56d516e10cdad6691f254ec9cb11f11ea364f7de

Review due: 2027-02-17

Context

+

An earlier draft of net-kingdom/canon/standards/tenancy-posture_v0.1.md §8.2 proposed that database placement policy — dedicated versus shared, and when that changes — be owned by railiance-platform, co-signed by adaptive-pricing. tenant-engine raised the same gap independently on 2026-08-16: both patterns are live on railiance01, neither is written down, and each new service copies whichever neighbour it looked at.

+

The complication is that this repo no longer holds the specs. RAILIANCE-WP-0012 and RAILIANCE-WP-0015 moved the deployable surface to the rapp-* repos. platform-pg's instances, max_connections, memory limit and retention are rapp-postgres's cluster CR. Tenancy Posture §19.8 nonetheless asks this repo for platform-pg's declared maximum size — a question one hop from where its answer lives.

+

Accepting ownership without stating this would produce either an answer we cannot substantiate or a quiet non-answer.

+
+

Decision

+

Accept placement ownership, split along rule and number.

+

This repo owns the rule: the default placement level, what overrides it, who is accountable for each workload's placement, that a shared cluster must publish a ceiling and an overflow target before its third consumer, that retention has a floor and a ceiling, and that a consumer's erasure horizon on shared substrate is disclosed rather than inherited silently.

+

The package repo owns the number: what the ceiling actually is, which resource binds first, what the retention values are, and the validator that enforces them where the CR lives.

+

Placement ownership per workload sits with the consuming repo; this repo co-signs. The consumer knows its latency requirement, erasure horizon and compliance position; S3 knows the substrate. A placement change needs both. Putting the decision solely here would recreate the problem §8.2 exists to avoid — an operations-shaped repo holding a commercial decision alone.

+

adaptive-pricing declined the standing co-signature on 2026-08-17. The replacement is binding and machine-reconcilable: it publishes typed tier minimums; this policy validates placement against them. Ownership stays here.

+
+

Consequences

+
  • docs/placement-policy.md is the operative document; this ADR is the decision behind it.
  • §19.8 is answered for platform-pg by rapp-postgres ADR-0004: four consumers, with platform-pg-2 named as the still-absent overflow target. Rule P-4.1 still requires apps-pg to declare its own ceiling before its third consumer.
  • This repo owes apps-pg's ceiling under its own rule. A policy whose author is exempt is not a policy.
  • §8.1 requires triggers to be monitored. This repo has no monitoring plane, so the connection-and-memory-ceiling trigger is recorded unmonitored pending railiance-telemetry. Declaring a ceiling is a partial substitute — a written threshold is checkable by a human at provisioning, which beats a limit discovered by an OOM kill.
  • adaptive-pricing's decline is recorded as single policy ownership plus a mandatory typed constraint join, not as an absent signature.
+
+

Alternatives considered

+

Decline ownership; route it to rapp-postgres. They hold the specs and the operational knowledge. Rejected: placement is a cross-cluster question and rapp-postgres owns one package. A policy owned by one substrate's operator cannot govern movement between substrates.

+

Accept whole, including the numbers. Rejected: it would either re-import the deployable surface this repo deliberately gave up, or produce numbers restated here that drift from the CR — a second source of truth for exactly the values a consumer must be able to trust.

+
RPLAT-ADR-0002 · 1.0 · proposedrailiance-platform · docs/adr/ADR-0002-placement-policy-ownership.md · 56d516e10cdad6691f254ec9cb11f11ea364f7de
diff --git a/build/adr/railiance-private-by-default-exposure/v1/index.html b/build/adr/railiance-private-by-default-exposure/v1/index.html index ca3d8bc..c2871dd 100644 --- a/build/adr/railiance-private-by-default-exposure/v1/index.html +++ b/build/adr/railiance-private-by-default-exposure/v1/index.html @@ -1,6 +1,6 @@ - + Private-by-default Exposure -
RMASTER-ADR-0008 accepted · accepted-1 railiance-master reviewed 2026-08-15generated from canonical source — do not edit

Private-by-default Exposure

Source: railiance-master · docs/adr/ADR-0008-private-by-default-exposure.md · 883533ed8af1703cc9bb4a2b24137e325bbbda47

Review due: 2027-02-15

Date: 2026-08-15 Status: Accepted

+
RMASTER-ADR-0008 accepted · accepted-1 railiance-master reviewed 2026-08-15generated from canonical source — do not edit

Private-by-default Exposure

Source: railiance-master · docs/adr/ADR-0008-private-by-default-exposure.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d

Review due: 2027-02-15

Date: 2026-08-15 Status: Accepted

Context

ADR-0006 says a topology binding is not permission to run a workload in production. It does not say who may reach a listener. A working deploy, a hosts_rail / binds_rapp line, or an Ingress object has been enough to put something on the public internet.

Family readiness vocabularies are deliberately not unified (schemas/README.md). Reef lifecycle_state has no production-approved. Rapp readiness_state has no production-approved either. Exposure cannot be derived from those enums.

@@ -215,4 +215,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

Consequences

  • ADR-0006 still answers "may this binding run in production?" This ADR answers "who may reach the listener?" Do not merge the axes.
  • The three readiness enums stay distinct on purpose.
  • Family schemas grow an additive exposure field. Rapp data_classification: public is a different field and must not be reused as the posture name.
  • Implementation stays in the owning repos. This ADR does not install NetworkPolicy, UFW, Ingress, or tunnels.
  • Existing public surfaces on reef-railiance remain up until named as grants. This ADR is not a shutdown plan.
  • CoulombCore host inventory and Q7 / Goss reaction stay outside this decision.
-
RMASTER-ADR-0008 · accepted-1 · acceptedrailiance-master · docs/adr/ADR-0008-private-by-default-exposure.md · 883533ed8af1703cc9bb4a2b24137e325bbbda47
+
RMASTER-ADR-0008 · accepted-1 · acceptedrailiance-master · docs/adr/ADR-0008-private-by-default-exposure.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d
diff --git a/build/adr/railiance-rail-kubernetes-wave-1-boundary/v1/index.html b/build/adr/railiance-rail-kubernetes-wave-1-boundary/v1/index.html index 424025b..a2f9c57 100644 --- a/build/adr/railiance-rail-kubernetes-wave-1-boundary/v1/index.html +++ b/build/adr/railiance-rail-kubernetes-wave-1-boundary/v1/index.html @@ -1,6 +1,6 @@ - + Wave 1 rail-kubernetes Boundary -
RMASTER-ADR-0002 accepted · accepted-1 railiance-master reviewed 2026-07-25generated from canonical source — do not edit

Wave 1 rail-kubernetes Boundary

Source: railiance-master · docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md · 883533ed8af1703cc9bb4a2b24137e325bbbda47

Review due: 2027-01-25

Date: 2026-07-25 Status: Accepted

+
RMASTER-ADR-0002 accepted · accepted-1 railiance-master reviewed 2026-07-25generated from canonical source — do not edit

Wave 1 rail-kubernetes Boundary

Source: railiance-master · docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d

Review due: 2027-01-25

Date: 2026-07-25 Status: Accepted

Context

Railiance wants rail-* repos to represent workload execution contracts rather than abstract naming ideas.

Today, the concrete Kubernetes workload contract already exists, but it is embedded in railiance-cluster. That repo currently owns both:

@@ -215,4 +215,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

Notes

This ADR does not require all current files to move immediately.

It requires the ownership line to be explicit now, so practical repo separation can proceed without ambiguity.

-
RMASTER-ADR-0002 · accepted-1 · acceptedrailiance-master · docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md · 883533ed8af1703cc9bb4a2b24137e325bbbda47
+
RMASTER-ADR-0002 · accepted-1 · acceptedrailiance-master · docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d
diff --git a/build/adr/railiance-rapp-declaration-contract/v1/index.html b/build/adr/railiance-rapp-declaration-contract/v1/index.html index e915aa4..caad5cd 100644 --- a/build/adr/railiance-rapp-declaration-contract/v1/index.html +++ b/build/adr/railiance-rapp-declaration-contract/v1/index.html @@ -1,6 +1,6 @@ - + Rapp Declaration Contract -
RMASTER-ADR-0007 accepted · accepted-1 railiance-master reviewed 2026-08-13generated from canonical source — do not edit

Rapp Declaration Contract

Source: railiance-master · docs/adr/ADR-0007-rapp-declaration-contract.md · 883533ed8af1703cc9bb4a2b24137e325bbbda47

Review due: 2027-02-13

Date: 2026-08-13 Status: Accepted

+
RMASTER-ADR-0007 accepted · accepted-1 railiance-master reviewed 2026-08-13generated from canonical source — do not edit

Rapp Declaration Contract

Source: railiance-master · docs/adr/ADR-0007-rapp-declaration-contract.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d

Review due: 2027-02-13

Date: 2026-08-13 Status: Accepted

Context

RMASTER-WP-0017 through RMASTER-WP-0019 established the four-axis model and materialized the first family repos. The model held up. Its enforcement did not.

A 2026-08-11 survey by railiance-platform found that the three live rapp.yaml files were mutually unreadable: rollout, smoke, and rollback contracts used different shapes; metadata that both rails carry consistently appeared in only one rapp; reef-railiance bound_rapps listed rapp-qonto only, while rapp-openbao and rapp-postgres were already live on the same reef. docs/repo-family-bootstrap-contract.md named fields in prose and could not catch any of this.

@@ -207,4 +207,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

Consequences

  • Drift across family declarations fails in tools/validate-family-declarations.py instead of accumulating in prose.
  • railiance-platform RAILIANCE-WP-0015-T02 can converge rapp-openbao and rapp-postgres onto one shape. Migration belongs to the owning repos; this ADR does not move any declaration.
  • reef-railiance must stop treating bound_rapps: [rapp-qonto] as source of truth. The list is already stale.
  • Three further rapp-* repos (rapp-secrets-engine, rapp-tenant-engine, rapp-user-engine) carry the family prefix and no declaration. They are visible to the validator as undeclared and must be declared, renamed, or retired by their owners.
  • Calling the validator from fix-consistency still waits on the-custodian admitting the family prefixes into the classification standard. That sequencing is not this repo's.
-
RMASTER-ADR-0007 · accepted-1 · acceptedrailiance-master · docs/adr/ADR-0007-rapp-declaration-contract.md · 883533ed8af1703cc9bb4a2b24137e325bbbda47
+
RMASTER-ADR-0007 · accepted-1 · acceptedrailiance-master · docs/adr/ADR-0007-rapp-declaration-contract.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d
diff --git a/build/adr/railiance-rapp-first-wave-selection/v1/index.html b/build/adr/railiance-rapp-first-wave-selection/v1/index.html index 4a91fb6..8b7fe9d 100644 --- a/build/adr/railiance-rapp-first-wave-selection/v1/index.html +++ b/build/adr/railiance-rapp-first-wave-selection/v1/index.html @@ -1,6 +1,6 @@ - + First-Wave rapp Selection -
RMASTER-ADR-0003 accepted · accepted-1 railiance-master reviewed 2026-07-25generated from canonical source — do not edit

First-Wave rapp Selection

Source: railiance-master · docs/adr/ADR-0003-rapp-first-wave-selection.md · 883533ed8af1703cc9bb4a2b24137e325bbbda47

Review due: 2027-01-25

Date: 2026-07-25 Status: Accepted

+
RMASTER-ADR-0003 accepted · accepted-1 railiance-master reviewed 2026-07-25generated from canonical source — do not edit

First-Wave rapp Selection

Source: railiance-master · docs/adr/ADR-0003-rapp-first-wave-selection.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d

Review due: 2027-01-25

Date: 2026-07-25 Status: Accepted

Context

Railiance wants rapp-* repos to represent managed workload packages rather than new ownership layers.

The current workload surfaces already suggest several candidates:

@@ -213,4 +213,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

Notes

This ADR chooses sequence, not a mandatory destination for every workload in the ecosystem.

-
RMASTER-ADR-0003 · accepted-1 · acceptedrailiance-master · docs/adr/ADR-0003-rapp-first-wave-selection.md · 883533ed8af1703cc9bb4a2b24137e325bbbda47
+
RMASTER-ADR-0003 · accepted-1 · acceptedrailiance-master · docs/adr/ADR-0003-rapp-first-wave-selection.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d
diff --git a/build/adr/railiance-reef-production-admission/v1/index.html b/build/adr/railiance-reef-production-admission/v1/index.html index 1575326..4c67e96 100644 --- a/build/adr/railiance-reef-production-admission/v1/index.html +++ b/build/adr/railiance-reef-production-admission/v1/index.html @@ -1,6 +1,6 @@ - + Reef Production Admission -
RMASTER-ADR-0006 accepted · accepted-1 railiance-master reviewed 2026-08-15generated from canonical source — do not edit

Reef Production Admission

Source: railiance-master · docs/adr/ADR-0006-reef-production-admission.md · 883533ed8af1703cc9bb4a2b24137e325bbbda47

Review due: 2027-02-15

Date: 2026-07-26 Status: Accepted

+
RMASTER-ADR-0006 accepted · accepted-1 railiance-master reviewed 2026-08-15generated from canonical source — do not edit

Reef Production Admission

Source: railiance-master · docs/adr/ADR-0006-reef-production-admission.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d

Review due: 2027-02-15

Date: 2026-07-26 Status: Accepted

Context

Fabric topology can say that a reef hosts a rail or binds a workload, but that does not demonstrate capacity, isolation, recoverability, or approval for a critical internet-facing service.

@@ -203,4 +203,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

Consequences

  • hosts_rail and binds_rapp no longer imply deployability.
  • reef-railiance may host Knative in wave 2, but Qonto cannot be called production-approved solely from that declaration.
  • Repeated evidence collection should become functional automation.
  • production-approved is not permission to publish a listener. See ADR-0008.
-
RMASTER-ADR-0006 · accepted-1 · acceptedrailiance-master · docs/adr/ADR-0006-reef-production-admission.md · 883533ed8af1703cc9bb4a2b24137e325bbbda47
+
RMASTER-ADR-0006 · accepted-1 · acceptedrailiance-master · docs/adr/ADR-0006-reef-production-admission.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d
diff --git a/build/adr/railiance-repository-prefix/v1/index.html b/build/adr/railiance-repository-prefix/v1/index.html index 54c187a..8491304 100644 --- a/build/adr/railiance-repository-prefix/v1/index.html +++ b/build/adr/railiance-repository-prefix/v1/index.html @@ -1,6 +1,6 @@ - + Repository Prefix Architecture -
RMASTER-ADR-0001 accepted · accepted-1 railiance-master reviewed 2026-07-25generated from canonical source — do not edit

Repository Prefix Architecture

Source: railiance-master · docs/adr/ADR-0001-repository-prefix-architecture.md · 883533ed8af1703cc9bb4a2b24137e325bbbda47

Review due: 2027-01-25

Date: 2026-07-25 Status: Accepted

+
RMASTER-ADR-0001 accepted · accepted-1 railiance-master reviewed 2026-07-25generated from canonical source — do not edit

Repository Prefix Architecture

Source: railiance-master · docs/adr/ADR-0001-repository-prefix-architecture.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d

Review due: 2027-01-25

Date: 2026-07-25 Status: Accepted

Context

Railiance already has a meaningful set of ownership repos such as railiance-infra, railiance-cluster, railiance-platform, railiance-enablement, railiance-apps, railiance-forge, and railiance-fabric.

That structure is useful, but it does not by itself capture all of the dimensions Railiance now needs.

@@ -232,4 +232,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

Notes

This ADR defines the repository taxonomy. It does not yet mandate a full migration or rename of existing repos. Migration should happen when it produces clearer ownership and lower ambiguity, not merely for naming purity.

-
RMASTER-ADR-0001 · accepted-1 · acceptedrailiance-master · docs/adr/ADR-0001-repository-prefix-architecture.md · 883533ed8af1703cc9bb4a2b24137e325bbbda47
+
RMASTER-ADR-0001 · accepted-1 · acceptedrailiance-master · docs/adr/ADR-0001-repository-prefix-architecture.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d
diff --git a/build/adr/railiance-s3-platform-service-boundary/v1/index.html b/build/adr/railiance-s3-platform-service-boundary/v1/index.html new file mode 100644 index 0000000..2bc6cea --- /dev/null +++ b/build/adr/railiance-s3-platform-service-boundary/v1/index.html @@ -0,0 +1,209 @@ + + + + +ADR-0001 — S3 owns platform services, not the substrate beneath them + +
RPLAT-ADR-0001 accepted · 1.0 railiance-platform reviewed 2026-08-17generated from canonical source — do not edit

ADR-0001 — S3 owns platform services, not the substrate beneath them

Source: railiance-platform · docs/adr/ADR-0001-s3-platform-service-boundary.md · 56d516e10cdad6691f254ec9cb11f11ea364f7de

Review due: 2027-02-17

Context

+

railiance-platform is S3 on the OAS Stack: the shared services several applications depend on — PostgreSQL, secrets, cache, object storage. The layers around it are S1 railiance-infra (OS and host concerns), S2 railiance-cluster (Kubernetes runtime, ingress), S4 railiance-enablement (tooling and CI), S5 railiance-apps (workloads).

+

This boundary has been stated in SCOPE.md and in ADR-003 of railiance-infra since the five-repo split, and it has been tested twice. RAIL-PL-WP-0001 existed to extract platform services out of S2 subcharts. On 2026-08-17 POLICY-NEXUS-WP-0001 assigned this repo "the substrate — DNS, TLS, ingress, hosting" for policy.coulomb.social, which would move the boundary back the other way.

+

The pressure is predictable and will recur: S3 is the layer that looks like it owns infrastructure, because it owns things that feel infrastructural. Recording the rule as an ADR rather than as a line in SCOPE.md gives future requests something to be answered against.

+
+

Decision

+

**S3 owns shared platform services and the interfaces consumers bind to. It does not own DNS, TLS, Kubernetes ingress, host configuration, or CI.** A request that would place any of those here is redirected to S1, S2 or S4 rather than absorbed, even when this repo is the closest available owner and even when absorbing it would be faster.

+

Where S3 has a genuine part in such a request — an object-storage bucket, a credential lane, a database — it supplies that part and co-signs the rest. It does not become the owner of the whole by being the first repo asked.

+
+

Consequences

+
  • POLICY-NEXUS-WP-0001 T04 needs splitting: ingress and TLS to S2, DNS to S1 or the reef boundary, storage and credentials here. Routed as RPF-WP-0018 finding F1.
  • A request this repo declines does not thereby become nobody's. Declining carries an obligation to name the owner, which is why F1 names two.
  • The rule cuts against this repo's convenience in the common case. That is what makes it a rule rather than a preference.
  • rapp-openbao and rapp-postgres are the same principle applied inward: the deployable package left, custody and policy stayed. See docs/rapp-openbao-boundary.md and docs/rapp-postgres-boundary.md.
+
+

Alternatives considered

+

Accept the substrate assignment as written. Fastest, and the requester had already resolved it with the operator. Rejected: it re-imports the coupling RAIL-PL-WP-0001 spent a workplan removing, and a boundary that yields to whoever asks most recently is not a boundary.

+

Own ingress for S3-adjacent services only. A narrower version, and it fails on the first argument about what counts as adjacent. The line has to be drawn where it can be checked.

+
RPLAT-ADR-0001 · 1.0 · acceptedrailiance-platform · docs/adr/ADR-0001-s3-platform-service-boundary.md · 56d516e10cdad6691f254ec9cb11f11ea364f7de
diff --git a/build/adr/railiance-s3-platform-service-boundary/v1/revisions/1.0/index.html b/build/adr/railiance-s3-platform-service-boundary/v1/revisions/1.0/index.html new file mode 100644 index 0000000..2bc6cea --- /dev/null +++ b/build/adr/railiance-s3-platform-service-boundary/v1/revisions/1.0/index.html @@ -0,0 +1,209 @@ + + + + +ADR-0001 — S3 owns platform services, not the substrate beneath them + +
RPLAT-ADR-0001 accepted · 1.0 railiance-platform reviewed 2026-08-17generated from canonical source — do not edit

ADR-0001 — S3 owns platform services, not the substrate beneath them

Source: railiance-platform · docs/adr/ADR-0001-s3-platform-service-boundary.md · 56d516e10cdad6691f254ec9cb11f11ea364f7de

Review due: 2027-02-17

Context

+

railiance-platform is S3 on the OAS Stack: the shared services several applications depend on — PostgreSQL, secrets, cache, object storage. The layers around it are S1 railiance-infra (OS and host concerns), S2 railiance-cluster (Kubernetes runtime, ingress), S4 railiance-enablement (tooling and CI), S5 railiance-apps (workloads).

+

This boundary has been stated in SCOPE.md and in ADR-003 of railiance-infra since the five-repo split, and it has been tested twice. RAIL-PL-WP-0001 existed to extract platform services out of S2 subcharts. On 2026-08-17 POLICY-NEXUS-WP-0001 assigned this repo "the substrate — DNS, TLS, ingress, hosting" for policy.coulomb.social, which would move the boundary back the other way.

+

The pressure is predictable and will recur: S3 is the layer that looks like it owns infrastructure, because it owns things that feel infrastructural. Recording the rule as an ADR rather than as a line in SCOPE.md gives future requests something to be answered against.

+
+

Decision

+

**S3 owns shared platform services and the interfaces consumers bind to. It does not own DNS, TLS, Kubernetes ingress, host configuration, or CI.** A request that would place any of those here is redirected to S1, S2 or S4 rather than absorbed, even when this repo is the closest available owner and even when absorbing it would be faster.

+

Where S3 has a genuine part in such a request — an object-storage bucket, a credential lane, a database — it supplies that part and co-signs the rest. It does not become the owner of the whole by being the first repo asked.

+
+

Consequences

+
  • POLICY-NEXUS-WP-0001 T04 needs splitting: ingress and TLS to S2, DNS to S1 or the reef boundary, storage and credentials here. Routed as RPF-WP-0018 finding F1.
  • A request this repo declines does not thereby become nobody's. Declining carries an obligation to name the owner, which is why F1 names two.
  • The rule cuts against this repo's convenience in the common case. That is what makes it a rule rather than a preference.
  • rapp-openbao and rapp-postgres are the same principle applied inward: the deployable package left, custody and policy stayed. See docs/rapp-openbao-boundary.md and docs/rapp-postgres-boundary.md.
+
+

Alternatives considered

+

Accept the substrate assignment as written. Fastest, and the requester had already resolved it with the operator. Rejected: it re-imports the coupling RAIL-PL-WP-0001 spent a workplan removing, and a boundary that yields to whoever asks most recently is not a boundary.

+

Own ingress for S3-adjacent services only. A narrower version, and it fails on the first argument about what counts as adjacent. The line has to be drawn where it can be checked.

+
RPLAT-ADR-0001 · 1.0 · acceptedrailiance-platform · docs/adr/ADR-0001-s3-platform-service-boundary.md · 56d516e10cdad6691f254ec9cb11f11ea364f7de
diff --git a/build/architecture/coulomb-estate/v0.1/index.html b/build/architecture/coulomb-estate/v0.1/index.html index 637911c..4a1aeba 100644 --- a/build/architecture/coulomb-estate/v0.1/index.html +++ b/build/architecture/coulomb-estate/v0.1/index.html @@ -1,7 +1,7 @@ - - + + Coulomb estate architecture -
coulomb-estate-architecture proposed · draft-1 the-custodian reviewed 2026-08-18generated from canonical source — do not edit

Coulomb estate architecture

Source: the-custodian · canon/architecture/coulomb-estate_v0.1.md · 5b51623198d9959793762f447f5813960c0b5df8

Review due: 2027-02-18

About this document

+
coulomb-estate-architecture proposed · draft-2 the-custodian reviewed 2026-08-19generated from canonical source — do not edit

Coulomb estate architecture

Source: the-custodian · canon/architecture/coulomb-estate_v0.1.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb

Review due: 2027-02-19

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.

01Introduction and Goals

@@ -259,8 +259,8 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

09Architecture Decisions

Estate ADRs in the-custodian/canon/architecture/. Publication ids still need repo prefixes (WP-0003). Status is the source front-matter.

-
SourceStatusDecision
adr-001-workplans-as-repo-artefacts.mdacceptedWorkplans and tasks originate as repo files; the hub is a read model.
adr-002-custodian-agent-runtime-design.mdacceptedCustodian agent runtime design.
adr-003-materialized-derived-state.mdacceptedHub state is derived and fingerprint-invalidated.
adr-004-connectivity-first-network-posture.mdacceptedConnectivity-first network posture.
adr-005-cross-repo-workplans-project-repos.mdacceptedCross-repo work lives in a prj-* repo.
adr-006-canon-federation-concept-ownership.mdacceptedThree canons; import, do not redefine.
adr-007-workplan-identity-and-repo-worker-topology.mdacceptedGlobally unique workplan ids; one registrar.
adr-008-multi-tenancy-model.mdsupersededRelocated to NetKingdom Tenancy Posture.
adr-010-hub-authority-and-local-cache-model.mdproposedTwo kinds of hub data; local cache vs authority.
adr-011-federated-namespaces-and-reconciliation-limits.mdproposedFederated namespaces and reconciliation limits.
-

Related, not estate-owned: policy-nexus ADR-0001 (addressing), NetKingdom Tenancy Posture (published), railiance-master ADR-0001–0008 (published).

+
IdStatusDecision
CUST-ADR-001acceptedWorkplans and tasks originate as repo files; the hub is a read model.
CUST-ADR-002acceptedCustodian agent runtime design.
CUST-ADR-003acceptedHub state is derived and fingerprint-invalidated.
CUST-ADR-004acceptedConnectivity-first network posture.
CUST-ADR-005acceptedCross-repo work lives in a prj-* repo.
CUST-ADR-006acceptedThree canons; import, do not redefine.
CUST-ADR-007acceptedGlobally unique workplan ids; one registrar.
adr-008supersededRelocated to NetKingdom Tenancy Posture.
CUST-ADR-010proposedTwo kinds of hub data; local cache vs authority.
CUST-ADR-011proposedFederated 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.

10Quality Requirements

@@ -271,4 +271,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

12Glossary

TermMeaning
EstateThe set of Coulomb / Custodian repos, canons, hubs, and rails.
CanonGoverning documents owned by one of the three federated canons.
Read modelA derived index. Never the origin of work or decisions.
Publication entryOne explicit object in policy-nexus publication.json.
First-wave completeChapters 1, 3, 4, 5.1, 9 and 12 are real; others real or N/A.
Project repoA prj-* repo that coordinates cross-repo work (ADR-005).
-
coulomb-estate-architecture · draft-1 · proposedthe-custodian · canon/architecture/coulomb-estate_v0.1.md · 5b51623198d9959793762f447f5813960c0b5df8
+
coulomb-estate-architecture · draft-2 · proposedthe-custodian · canon/architecture/coulomb-estate_v0.1.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb
diff --git a/build/architecture/coulomb-estate/v0.1/revisions/draft-2/index.html b/build/architecture/coulomb-estate/v0.1/revisions/draft-2/index.html new file mode 100644 index 0000000..4a1aeba --- /dev/null +++ b/build/architecture/coulomb-estate/v0.1/revisions/draft-2/index.html @@ -0,0 +1,274 @@ + + + + +Coulomb estate architecture + +
coulomb-estate-architecture proposed · draft-2 the-custodian reviewed 2026-08-19generated from canonical source — do not edit

Coulomb estate architecture

Source: the-custodian · canon/architecture/coulomb-estate_v0.1.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb

Review due: 2027-02-19

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.

+
+

01Introduction 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

+
RoleConcern
OperatorWhat must be discussed in person; ratification.
the-custodianCanon, values, constitution, estate ADRs.
Product reposImplementation and per-repo ADRs.
railiance-platformSubstrate: DNS, TLS, ingress, hosting.
policy-nexusPublication only.
info-tech-canonSemantic model, not this estate's building blocks.
+
+

02Architecture 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.

+
+

03System 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

+
NeighbourInterface
Owning git reposSource of workplans, ADRs, canon.
State HubDerived index / cache of those files.
policy.coulomb.socialGenerated publication of canon and ADRs.
Railiance reefRuntime for hubs, rApps, Forgejo.
NetKingdomIdentity, tenancy, IAM profile.
info-tech-canonImported semantics, not estate structure.
+
+

04Solution 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).
+
+

05Building 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.

+
+

06Runtime View

+

N/A — estate coordination is file sync plus hub rebuild, not a single runtime scenario. System runtimes belong in their own arc42.

+
+

07Deployment View

+

N/A — Railiance owns where things run. This document names the substrate; it does not map nodes.

+
+

08Cross-Cutting Concepts

+

N/A in this revision. Concept ownership and the hub/cache split are already in §4 and the ADRs in §9.

+
+

09Architecture Decisions

+

Estate ADRs in the-custodian/canon/architecture/. Publication ids still need repo prefixes (WP-0003). Status is the source front-matter.

+
IdStatusDecision
CUST-ADR-001acceptedWorkplans and tasks originate as repo files; the hub is a read model.
CUST-ADR-002acceptedCustodian agent runtime design.
CUST-ADR-003acceptedHub state is derived and fingerprint-invalidated.
CUST-ADR-004acceptedConnectivity-first network posture.
CUST-ADR-005acceptedCross-repo work lives in a prj-* repo.
CUST-ADR-006acceptedThree canons; import, do not redefine.
CUST-ADR-007acceptedGlobally unique workplan ids; one registrar.
adr-008supersededRelocated to NetKingdom Tenancy Posture.
CUST-ADR-010proposedTwo kinds of hub data; local cache vs authority.
CUST-ADR-011proposedFederated 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.

+
+

10Quality Requirements

+

N/A in this revision — rebuildability and currency already have mechanical checks (fix-consistency, make currency).

+
+

11Risks 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.

+
+

12Glossary

+
TermMeaning
EstateThe set of Coulomb / Custodian repos, canons, hubs, and rails.
CanonGoverning documents owned by one of the three federated canons.
Read modelA derived index. Never the origin of work or decisions.
Publication entryOne explicit object in policy-nexus publication.json.
First-wave completeChapters 1, 3, 4, 5.1, 9 and 12 are real; others real or N/A.
Project repoA prj-* repo that coordinates cross-repo work (ADR-005).
+
coulomb-estate-architecture · draft-2 · proposedthe-custodian · canon/architecture/coulomb-estate_v0.1.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb
diff --git a/build/architecture/net-kingdom/v0.1/index.html b/build/architecture/net-kingdom/v0.1/index.html index e5dd21c..ba6c71a 100644 --- a/build/architecture/net-kingdom/v0.1/index.html +++ b/build/architecture/net-kingdom/v0.1/index.html @@ -1,7 +1,7 @@ - - + + NetKingdom architecture -
net-kingdom-architecture proposed · draft-1 net-kingdom reviewed 2026-08-18generated from canonical source — do not edit

NetKingdom architecture

Source: net-kingdom · docs/architecture/net-kingdom_v0.1.md · 0e0962e68b39fdcfb633b5058602174a36416a68

Review due: 2027-02-18

About this document

+
net-kingdom-architecture proposed · draft-2 net-kingdom reviewed 2026-08-19generated from canonical source — do not edit

NetKingdom architecture

Source: net-kingdom · docs/architecture/net-kingdom_v0.1.md · ccc2618daee997bb4bd4249613d7c4c7344845cf

Review due: 2027-02-19

About this document

First-wave arc42 for NetKingdom: the estate's identity and tenancy security core. Chapter 9 lists governing ADRs and standards; it does not paste them.

01Introduction and Goals

@@ -230,7 +230,7 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

N/A for this stub.

09Architecture Decisions

-
SourceStatusNotes
canon/standards/tenancy-posture_v0.1.mdproposedPublished. First publication of this site.
canon/standards/iam-profile_v0.3.mdacceptedCurrent profile. Needs a unique publication id (v0.2 still shares netkingdom-iam-profile).
canon/standards/iam-profile_v0.2.mdshould be supersededv0.3 supersedes it; front-matter still accepted.
docs/adr/ADR-0006 … ADR-0015see filesIdentity, orchestration, IAM ownership, tenant roles, packaging. Publish after NK-ADR-* prefix and review metadata.
+
SourceStatusNotes
canon/standards/tenancy-posture_v0.1.mdproposedPublished. First publication of this site.
canon/standards/iam-profile_v0.3.mdacceptedCurrent profile (netkingdom-iam-profile-v0.3).
canon/standards/iam-profile_v0.2.mdsupersededPredecessor of v0.3.
docs/adr/ADR-0006 … ADR-0015see filesIdentity, orchestration, IAM ownership, tenant roles, packaging. Publish after NK-ADR-* prefix and review metadata.

Custodian ADR-008 is superseded by Tenancy Posture and is not current.

10Quality Requirements

@@ -241,4 +241,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

12Glossary

TermMeaning
IAM ProfileProvider-neutral OIDC contract owned here.
Tenancy PostureGraduated axes for describing multi-tenancy.
Tenant-engineLifecycle and capability roles for tenants.
-
net-kingdom-architecture · draft-1 · proposednet-kingdom · docs/architecture/net-kingdom_v0.1.md · 0e0962e68b39fdcfb633b5058602174a36416a68
+
net-kingdom-architecture · draft-2 · proposednet-kingdom · docs/architecture/net-kingdom_v0.1.md · ccc2618daee997bb4bd4249613d7c4c7344845cf
diff --git a/build/architecture/net-kingdom/v0.1/revisions/draft-2/index.html b/build/architecture/net-kingdom/v0.1/revisions/draft-2/index.html new file mode 100644 index 0000000..ba6c71a --- /dev/null +++ b/build/architecture/net-kingdom/v0.1/revisions/draft-2/index.html @@ -0,0 +1,244 @@ + + + + +NetKingdom architecture + +
net-kingdom-architecture proposed · draft-2 net-kingdom reviewed 2026-08-19generated from canonical source — do not edit

NetKingdom architecture

Source: net-kingdom · docs/architecture/net-kingdom_v0.1.md · ccc2618daee997bb4bd4249613d7c4c7344845cf

Review due: 2027-02-19

About this document

+

First-wave arc42 for NetKingdom: the estate's identity and tenancy security core. Chapter 9 lists governing ADRs and standards; it does not paste them.

+
+

01Introduction and Goals

+

NetKingdom is the open security core for DevSecOps on Kubernetes. It owns identity, tenancy posture, and the contracts that flex-auth, key-cape, tenant-engine, and railiance workloads implement.

+

1.1 Requirements Overview

+
  • One IAM profile, versioned, owned here.
  • Tenancy described as graduated axes, not a single on/off switch.
  • Workload packaging and credential vending have explicit boundaries.
+

1.2 Quality Goals

+
  1. Provider-neutral identity contract.
  2. Recursive multi-tenant authorization that implementers can declare.
  3. Honest about what is not there yet (Tenancy Posture).
+

1.3 Stakeholders

+
RoleConcern
net-kingdomCanon owner for identity and tenancy.
flex-auth / key-cape / tenant-engineImplementers of the contracts.
railiance-masterWorkload packaging on the rail.
the-custodianFederation; does not redefine these concepts.
+
+

02Architecture Constraints

+

N/A for this stub.

+
+

03System Scope and Context

+

In: IAM profile, tenancy posture, tenant/user-engine boundaries, credential management, playbook capability contract, NetKingdom ADRs. Out: publication (policy-nexus), rail runtime (railiance), estate work-factory (the-custodian).

+

3.1 Business Context

+

Security here is dynamic and adversarial. The system exists so implementers share one contract instead of copying a neighbour.

+

3.2 Technical Context

+

Consumers: flex-auth, key-cape, tenant-engine, audit-core, rApps. Published today: Tenancy Posture /standards/tenancy-posture/v0.1/.

+
+

04Solution Strategy

+

N/A for this stub — recursive multi-tenant identity (ADR-0006) and the IAM profile ownership rule (ADR-0011) are the spine.

+
+

05Building Block View

+

5.1 Level 1 – System/Top-Level

+

N/A for this stub.

+
+

06Runtime View

+

N/A for this stub.

+
+

07Deployment View

+

N/A for this stub.

+
+

08Cross-Cutting Concepts

+

N/A for this stub.

+
+

09Architecture Decisions

+
SourceStatusNotes
canon/standards/tenancy-posture_v0.1.mdproposedPublished. First publication of this site.
canon/standards/iam-profile_v0.3.mdacceptedCurrent profile (netkingdom-iam-profile-v0.3).
canon/standards/iam-profile_v0.2.mdsupersededPredecessor of v0.3.
docs/adr/ADR-0006 … ADR-0015see filesIdentity, orchestration, IAM ownership, tenant roles, packaging. Publish after NK-ADR-* prefix and review metadata.
+

Custodian ADR-008 is superseded by Tenancy Posture and is not current.

+
+

10Quality Requirements

+

N/A for this stub.

+
+

11Risks and Technical Debt

+

N/A for this stub. Residual: IAM Profile id collision (WP-0003 packet).

+
+

12Glossary

+
TermMeaning
IAM ProfileProvider-neutral OIDC contract owned here.
Tenancy PostureGraduated axes for describing multi-tenancy.
Tenant-engineLifecycle and capability roles for tenants.
+
net-kingdom-architecture · draft-2 · proposednet-kingdom · docs/architecture/net-kingdom_v0.1.md · ccc2618daee997bb4bd4249613d7c4c7344845cf
diff --git a/build/architecture/policy-nexus/v0.1/index.html b/build/architecture/policy-nexus/v0.1/index.html index 49b31fb..cd45956 100644 --- a/build/architecture/policy-nexus/v0.1/index.html +++ b/build/architecture/policy-nexus/v0.1/index.html @@ -1,6 +1,6 @@ - + Policy Nexus architecture -
policy-nexus-architecture proposed · draft-1 the-custodian reviewed 2026-08-18generated from canonical source — do not edit

Policy Nexus architecture

Source: policy-nexus · docs/architecture/policy-nexus_v0.1.md · 64b47d73b9fdf33df535db42c80db3a7435da5cf

Review due: 2027-02-18

About this document

+
policy-nexus-architecture proposed · draft-1 the-custodian reviewed 2026-08-18generated from canonical source — do not edit

Policy Nexus architecture

Source: policy-nexus · docs/architecture/policy-nexus_v0.1.md · 5cb88edf4d52a65ea31b1f2f53bcf6f71769d234

Review due: 2027-02-18

About this document

This document follows the arc42 template for the publication surface at policy.coulomb.social. It is the first-wave architecture document this repository is allowed to author. Other first-wave systems are written in their owning repos.

01Introduction and Goals

@@ -245,4 +245,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

12Glossary

TermMeaning
Current addressThe stable URL for the document as it now stands.
Revision addressWrite-once URL for one source digest.
Publication entryOne object in publication.json. Discovery is not publication.
First-wave completeChapters 1, 3, 4, 5.1, 9 and 12 are real; others real or N/A.
-
policy-nexus-architecture · draft-1 · proposedpolicy-nexus · docs/architecture/policy-nexus_v0.1.md · 64b47d73b9fdf33df535db42c80db3a7435da5cf
+
policy-nexus-architecture · draft-1 · proposedpolicy-nexus · docs/architecture/policy-nexus_v0.1.md · 5cb88edf4d52a65ea31b1f2f53bcf6f71769d234
diff --git a/build/architecture/railiance/v0.1/index.html b/build/architecture/railiance/v0.1/index.html index 7ea7fe8..14c9b02 100644 --- a/build/architecture/railiance/v0.1/index.html +++ b/build/architecture/railiance/v0.1/index.html @@ -1,7 +1,7 @@ - - + + Railiance architecture -
railiance-architecture proposed · draft-1 railiance-master reviewed 2026-08-18generated from canonical source — do not edit

Railiance architecture

Source: railiance-master · docs/architecture/railiance_v0.1.md · 883533ed8af1703cc9bb4a2b24137e325bbbda47

Review due: 2027-02-18

About this document

+
railiance-architecture proposed · draft-2 railiance-master reviewed 2026-08-19generated from canonical source — do not edit

Railiance architecture

Source: railiance-master · docs/architecture/railiance_v0.1.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d

Review due: 2027-02-19

About this document

First-wave arc42 for the Railiance runtime substrate. Deeper chapters belong to follow-on work in this repo. Chapter 9 lists the ADRs this repo already publishes; it does not paste them.

01Introduction and Goals

@@ -232,6 +232,7 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

09Architecture Decisions

Published on policy.coulomb.social from this repo:

IdStatusDecision
RMASTER-ADR-0001acceptedRepository prefix architecture
RMASTER-ADR-0002acceptedWave 1 rail-kubernetes boundary
RMASTER-ADR-0003acceptedFirst-wave rapp selection
RMASTER-ADR-0004acceptedFirst-wave reef rollout
RMASTER-ADR-0005acceptedDerived rail composition
RMASTER-ADR-0006acceptedReef production admission
RMASTER-ADR-0007acceptedRapp declaration contract
RMASTER-ADR-0008acceptedPrivate-by-default exposure
+

Also published from railiance-platform: RPLAT-ADR-0001 (S3 platform services), RPLAT-ADR-0002 (placement rule), RPLAT-ADR-0003 (decisions live in the repo).

Unresolved: identical accepted ADR-003/004 copies in railiance-hosts and railiance-infra. Not listed as current here until those owners rule.

10Quality Requirements

@@ -242,4 +243,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

12Glossary

TermMeaning
RailA composed runtime path.
ReefThe production admission environment.
rAppA packaged workload bound by a declaration contract.
-
railiance-architecture · draft-1 · proposedrailiance-master · docs/architecture/railiance_v0.1.md · 883533ed8af1703cc9bb4a2b24137e325bbbda47
+
railiance-architecture · draft-2 · proposedrailiance-master · docs/architecture/railiance_v0.1.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d
diff --git a/build/architecture/railiance/v0.1/revisions/draft-2/index.html b/build/architecture/railiance/v0.1/revisions/draft-2/index.html new file mode 100644 index 0000000..14c9b02 --- /dev/null +++ b/build/architecture/railiance/v0.1/revisions/draft-2/index.html @@ -0,0 +1,246 @@ + + + + +Railiance architecture + +
railiance-architecture proposed · draft-2 railiance-master reviewed 2026-08-19generated from canonical source — do not edit

Railiance architecture

Source: railiance-master · docs/architecture/railiance_v0.1.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d

Review due: 2027-02-19

About this document

+

First-wave arc42 for the Railiance runtime substrate. Deeper chapters belong to follow-on work in this repo. Chapter 9 lists the ADRs this repo already publishes; it does not paste them.

+
+

01Introduction and Goals

+

Railiance-master is the authoritative source for Railiance framework architecture: repo families, workload models, and substrate boundaries that implementation repos must not invent locally.

+

1.1 Requirements Overview

+
  • Name the rails, reefs, and rApps and who owns each boundary.
  • Keep those decisions in docs/adr/ with publication-grade metadata.
  • Consume platform packages; do not fork identity or tenancy.
+

1.2 Quality Goals

+
  1. Reviewable boundary decisions.
  2. Private-by-default exposure until admission.
  3. Derived rails compose; they do not fork policy.
+

1.3 Stakeholders

+
RoleConcern
railiance-masterFramework language and first-wave rApp set.
railiance-platformS3, placement, substrate services.
railiance-appsProduction digest bindings.
NetKingdomIdentity and tenancy posture of workloads.
+
+

02Architecture Constraints

+

N/A for this stub.

+
+

03System Scope and Context

+

In: rails, reefs, rApp packaging, admission, exposure defaults. Out: tenant identity semantics (NetKingdom), publication of policy (policy-nexus), OS baseline (railiance-hosts).

+

3.1 Business Context

+

Implementation repos solve immediate cluster problems. This system holds the shared meaning so those repos do not drift.

+

3.2 Technical Context

+

Neighbours: railiance-platform, railiance-apps, rapp-* packages, the reef (Traefik, cert-manager), Forgejo, NetKingdom, policy-nexus.

+
+

04Solution Strategy

+

N/A for this stub — repository-prefix architecture and rapp-first wave are already in the ADRs in §9.

+
+

05Building Block View

+

5.1 Level 1 – System/Top-Level

+

N/A for this stub.

+
+

06Runtime View

+

N/A for this stub.

+
+

07Deployment View

+

N/A for this stub.

+
+

08Cross-Cutting Concepts

+

N/A for this stub.

+
+

09Architecture Decisions

+

Published on policy.coulomb.social from this repo:

+
IdStatusDecision
RMASTER-ADR-0001acceptedRepository prefix architecture
RMASTER-ADR-0002acceptedWave 1 rail-kubernetes boundary
RMASTER-ADR-0003acceptedFirst-wave rapp selection
RMASTER-ADR-0004acceptedFirst-wave reef rollout
RMASTER-ADR-0005acceptedDerived rail composition
RMASTER-ADR-0006acceptedReef production admission
RMASTER-ADR-0007acceptedRapp declaration contract
RMASTER-ADR-0008acceptedPrivate-by-default exposure
+

Also published from railiance-platform: RPLAT-ADR-0001 (S3 platform services), RPLAT-ADR-0002 (placement rule), RPLAT-ADR-0003 (decisions live in the repo).

+

Unresolved: identical accepted ADR-003/004 copies in railiance-hosts and railiance-infra. Not listed as current here until those owners rule.

+
+

10Quality Requirements

+

N/A for this stub.

+
+

11Risks and Technical Debt

+

N/A for this stub.

+
+

12Glossary

+
TermMeaning
RailA composed runtime path.
ReefThe production admission environment.
rAppA packaged workload bound by a declaration contract.
+
railiance-architecture · draft-2 · proposedrailiance-master · docs/architecture/railiance_v0.1.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d
diff --git a/build/architecture/state-hub/v0.1/index.html b/build/architecture/state-hub/v0.1/index.html index 72daa0b..da9d207 100644 --- a/build/architecture/state-hub/v0.1/index.html +++ b/build/architecture/state-hub/v0.1/index.html @@ -1,7 +1,7 @@ - - + + State Hub architecture -
state-hub-architecture proposed · draft-1 state-hub reviewed 2026-08-18generated from canonical source — do not edit

State Hub architecture

Source: state-hub · docs/architecture/state-hub_v0.1.md · b606d5d44c6bcb3ff438656acae3bf93a786104b

Review due: 2027-02-18

About this document

+
state-hub-architecture proposed · draft-2 state-hub reviewed 2026-08-19generated from canonical source — do not edit

State Hub architecture

Source: state-hub · docs/architecture/state-hub_v0.1.md · 8585bb0c1d0f19e3d55e901e2041edf6aff03f0a

Review due: 2027-02-19

About this document

First-wave arc42 for State Hub, the estate's live coordination read-model. This service is in active retirement planning; new permanent ownership should not land here. Chapter 9 points at the estate ADRs that still bind it.

01Introduction and Goals

@@ -232,7 +232,7 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

09Architecture Decisions

This repo has no docs/adr/ corpus. Binding decisions live in the-custodian and are listed on the estate map:

-
Estate ADRStatusWhy it binds this system
CUST-ADR-001 (workplans as repo artefacts)acceptedHub is a read model.
CUST-ADR-003 (materialized derived state)acceptedHow the cache invalidates.
CUST-ADR-007 (identity and registrar)acceptedOne writer of workplan UUIDs.
CUST-ADR-010 (hub authority / local cache)proposedTwo kinds of hub data.
+
Estate ADRStatusWhy it binds this system
CUST-ADR-001acceptedHub is a read model. Published /adr/custodian-workplans-as-repo-artefacts/v1/.
CUST-ADR-003acceptedHow the cache invalidates.
CUST-ADR-007acceptedOne writer of workplan UUIDs.
CUST-ADR-010proposedTwo kinds of hub data.

Do not treat a State Hub /decisions row as the published ADR.

10Quality Requirements

@@ -243,4 +243,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off

12Glossary

TermMeaning
Read modelDerived index; never the origin.
RegistrarThe single instance allowed to mint workplan UUIDs.
RetirementCoordinated move of capabilities out of this repo.
-
state-hub-architecture · draft-1 · proposedstate-hub · docs/architecture/state-hub_v0.1.md · b606d5d44c6bcb3ff438656acae3bf93a786104b
+
state-hub-architecture · draft-2 · proposedstate-hub · docs/architecture/state-hub_v0.1.md · 8585bb0c1d0f19e3d55e901e2041edf6aff03f0a
diff --git a/build/architecture/state-hub/v0.1/revisions/draft-2/index.html b/build/architecture/state-hub/v0.1/revisions/draft-2/index.html new file mode 100644 index 0000000..da9d207 --- /dev/null +++ b/build/architecture/state-hub/v0.1/revisions/draft-2/index.html @@ -0,0 +1,246 @@ + + + + +State Hub architecture + +
state-hub-architecture proposed · draft-2 state-hub reviewed 2026-08-19generated from canonical source — do not edit

State Hub architecture

Source: state-hub · docs/architecture/state-hub_v0.1.md · 8585bb0c1d0f19e3d55e901e2041edf6aff03f0a

Review due: 2027-02-19

About this document

+

First-wave arc42 for State Hub, the estate's live coordination read-model. This service is in active retirement planning; new permanent ownership should not land here. Chapter 9 points at the estate ADRs that still bind it.

+
+

01Introduction and Goals

+

State Hub is a queryable, auditable memory of work: domains, repos, workplans, tasks, decisions, progress. Files remain the origin. The hub is derived state (custodian ADR-001, ADR-003).

+

It remains operational until retirement gates in prj-state-hub-retirement are met. Replacement ownership is moving toward repo-manager and hub-core.

+

1.1 Requirements Overview

+
  • Rebuild coordination state from registered repository files.
  • One identifier registrar (ADR-007). This workstation is not it.
  • Preserve compatibility; do not take new permanent architectural ownership.
+

1.2 Quality Goals

+
  1. Rebuildability from git.
  2. Hub never becomes the origin of work.
  3. Extraction paths stay open.
+

1.3 Stakeholders

+
RoleConcern
state-hubLive read-model during retirement.
the-custodianEstate rules the hub must not invert.
repo-managerIncoming consistency / repo representation.
product reposWorkplan files the hub indexes.
+
+

02Architecture Constraints

+

N/A for this stub — retirement program is the binding constraint.

+
+

03System Scope and Context

+

In: indexing workplans/tasks/decisions, consistency rebuild, query API and dashboard used today. Out: being the source of work items; new cross-domain capabilities; publication of policy (policy-nexus).

+

3.1 Business Context

+

Files are excellent for canon and provenance. The estate still needs a live query surface while retirement proceeds.

+

3.2 Technical Context

+

Inputs: workplan markdown via fix-consistency. Outputs: HTTP/MCP APIs. Neighbours: every registered repo, activity-core (ops runs), policy-nexus (does not index the hub).

+
+

04Solution Strategy

+

N/A for this stub. The strategy is already in the estate ADRs: files first, materialized derived state, single registrar, local cache vs authority (ADR-010, proposed).

+
+

05Building Block View

+

5.1 Level 1 – System/Top-Level

+

N/A for this stub.

+
+

06Runtime View

+

N/A for this stub.

+
+

07Deployment View

+

N/A for this stub.

+
+

08Cross-Cutting Concepts

+

N/A for this stub.

+
+

09Architecture Decisions

+

This repo has no docs/adr/ corpus. Binding decisions live in the-custodian and are listed on the estate map:

+
Estate ADRStatusWhy it binds this system
CUST-ADR-001acceptedHub is a read model. Published /adr/custodian-workplans-as-repo-artefacts/v1/.
CUST-ADR-003acceptedHow the cache invalidates.
CUST-ADR-007acceptedOne writer of workplan UUIDs.
CUST-ADR-010proposedTwo kinds of hub data.
+

Do not treat a State Hub /decisions row as the published ADR.

+
+

10Quality Requirements

+

N/A for this stub.

+
+

11Risks and Technical Debt

+

N/A for this stub. Residual: this workstation cannot mint registrar UUIDs.

+
+

12Glossary

+
TermMeaning
Read modelDerived index; never the origin.
RegistrarThe single instance allowed to mint workplan UUIDs.
RetirementCoordinated move of capabilities out of this repo.
+
state-hub-architecture · draft-2 · proposedstate-hub · docs/architecture/state-hub_v0.1.md · 8585bb0c1d0f19e3d55e901e2041edf6aff03f0a
diff --git a/build/index.html b/build/index.html index 44801fd..ecca210 100644 --- a/build/index.html +++ b/build/index.html @@ -183,4 +183,4 @@ footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-fam .route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px} a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px} @media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}} -
policy surfacegenerated from canonical sources — do not edit

Coulomb Policy Nexus

Canon and architecture decisions at stable addresses, with visible currency.

DocumentStatusLifecycleRevisionOwnerReviewedReview dueCurrency
NetKingdom Tenancy Posture v0.1proposedactivedraft-8net-kingdom2026-08-172027-02-17current
Coulomb estate architectureproposedactivedraft-1the-custodian2026-08-182027-02-18current
Railiance architectureproposedactivedraft-1railiance-master2026-08-182027-02-18current
NetKingdom architectureproposedactivedraft-1net-kingdom2026-08-182027-02-18current
State Hub architectureproposedactivedraft-1state-hub2026-08-182027-02-18current
Policy Nexus architectureproposedactivedraft-1the-custodian2026-08-182027-02-18current
Policy addressing and permanenceacceptedactiveaccepted-1the-custodian2026-08-182027-02-18current
Repository Prefix Architectureacceptedactiveaccepted-1railiance-master2026-07-252027-01-25current
Wave 1 rail-kubernetes Boundaryacceptedactiveaccepted-1railiance-master2026-07-252027-01-25current
First-Wave rapp Selectionacceptedactiveaccepted-1railiance-master2026-07-252027-01-25current
First-Wave reef Rolloutacceptedactiveaccepted-1railiance-master2026-07-262027-01-26current
Derived Rail Compositionacceptedactiveaccepted-1railiance-master2026-07-262027-01-26current
Reef Production Admissionacceptedactiveaccepted-1railiance-master2026-08-152027-02-15current
Rapp Declaration Contractacceptedactiveaccepted-1railiance-master2026-08-132027-02-13current
Private-by-default Exposureacceptedactiveaccepted-1railiance-master2026-08-152027-02-15current
Activity-Core as Coulomb Org Event Bridgeacceptedactiveaccepted-1activity-core2026-05-142026-11-14current
Markdown-as-Definition Format for Event Types and ActivityDefinitionsacceptedactiveaccepted-1activity-core2026-05-142026-11-14current
Rule vs. Instruction Model and Expression DSLacceptedactiveaccepted-1activity-core2026-05-142026-11-14current
The Producer Trust Boundary — Guardrails and Error-Correction for Untrusted Outputacceptedactiveaccepted-1activity-core2026-06-262026-12-26current
Ops runs vs development work records — claim queue and plane splitacceptedactiveaccepted-1activity-core2026-08-032027-02-03current
ADR-0001 — The routing catalog is a pointer layer, never a second copyacceptedactive1ops-warden2026-08-182027-02-18current
ADR-0002 — ops-warden is a transparent conduit, never a secret brokeracceptedactive1ops-warden2026-08-182027-02-18current
ADR-0003 — Cover gaps, but never silently own themacceptedactive1ops-warden2026-08-182027-02-18current
ADR-0004 — High-risk lanes refuse raw value streaming to agent sessionsacceptedactive1ops-warden2026-08-182027-02-18current
ADR-0005 — Implement one lane narrowly, route everything elseacceptedactive1ops-warden2026-08-182027-02-18current
+
policy surfacegenerated from canonical sources — do not edit

Coulomb Policy Nexus

Canon and architecture decisions at stable addresses, with visible currency.

DocumentStatusLifecycleRevisionOwnerReviewedReview dueCurrency
NetKingdom Tenancy Posture v0.1proposedactivedraft-8net-kingdom2026-08-172027-02-17current
Coulomb estate architectureproposedactivedraft-2the-custodian2026-08-192027-02-19current
Railiance architectureproposedactivedraft-2railiance-master2026-08-192027-02-19current
NetKingdom architectureproposedactivedraft-2net-kingdom2026-08-192027-02-19current
State Hub architectureproposedactivedraft-2state-hub2026-08-192027-02-19current
Policy Nexus architectureproposedactivedraft-1the-custodian2026-08-182027-02-18current
Policy addressing and permanenceacceptedactiveaccepted-1the-custodian2026-08-182027-02-18current
Repository Prefix Architectureacceptedactiveaccepted-1railiance-master2026-07-252027-01-25current
Wave 1 rail-kubernetes Boundaryacceptedactiveaccepted-1railiance-master2026-07-252027-01-25current
First-Wave rapp Selectionacceptedactiveaccepted-1railiance-master2026-07-252027-01-25current
First-Wave reef Rolloutacceptedactiveaccepted-1railiance-master2026-07-262027-01-26current
Derived Rail Compositionacceptedactiveaccepted-1railiance-master2026-07-262027-01-26current
Reef Production Admissionacceptedactiveaccepted-1railiance-master2026-08-152027-02-15current
Rapp Declaration Contractacceptedactiveaccepted-1railiance-master2026-08-132027-02-13current
Private-by-default Exposureacceptedactiveaccepted-1railiance-master2026-08-152027-02-15current
Activity-Core as Coulomb Org Event Bridgeacceptedactiveaccepted-1activity-core2026-05-142026-11-14current
Markdown-as-Definition Format for Event Types and ActivityDefinitionsacceptedactiveaccepted-1activity-core2026-05-142026-11-14current
Rule vs. Instruction Model and Expression DSLacceptedactiveaccepted-1activity-core2026-05-142026-11-14current
The Producer Trust Boundary — Guardrails and Error-Correction for Untrusted Outputacceptedactiveaccepted-1activity-core2026-06-262026-12-26current
Ops runs vs development work records — claim queue and plane splitacceptedactiveaccepted-1activity-core2026-08-032027-02-03current
ADR-0001 — The routing catalog is a pointer layer, never a second copyacceptedactive1ops-warden2026-08-182027-02-18current
ADR-0002 — ops-warden is a transparent conduit, never a secret brokeracceptedactive1ops-warden2026-08-182027-02-18current
ADR-0003 — Cover gaps, but never silently own themacceptedactive1ops-warden2026-08-182027-02-18current
ADR-0004 — High-risk lanes refuse raw value streaming to agent sessionsacceptedactive1ops-warden2026-08-182027-02-18current
ADR-0005 — Implement one lane narrowly, route everything elseacceptedactive1ops-warden2026-08-182027-02-18current
Workplans and Work Items Are Repository Artefactsacceptedactiveaccepted-1the-custodian2026-02-282026-08-28current
Custodian Agent Runtime — v0.1 Bootstrap Designacceptedactiveaccepted-1the-custodian2026-03-122026-09-12current
Materialized Derived State with Fingerprint Invalidation for Repo-Sourced Dataacceptedactiveaccepted-1the-custodian2026-03-202026-09-20current
Connectivity-First Network Posture for Custodian Infrastructureacceptedactiveaccepted-1the-custodian2026-03-262026-09-26current
Cross-Repo Workplans Live in Dedicated Project Reposacceptedactiveaccepted-1the-custodian2026-06-222026-12-22current
Canon Federation and Concept Ownership Across InfoTech and Commerceacceptedactiveaccepted-1the-custodian2026-08-172027-02-17current
Workplan Identity Uniqueness, Single Registrar, and Repo Worker Topologyacceptedactiveaccepted-1the-custodian2026-08-172027-02-17current
Hub Authority, Local Cache, and the Two Kinds of Hub Dataproposedactivedraft-1the-custodian2026-08-172027-02-17current
Federated Namespaces: Four Planes, Declared Posture, and the Limits of Reconciliationproposedactivedraft-2the-custodian2026-08-172027-02-17current
ADR-0001 — S3 owns platform services, not the substrate beneath themacceptedactive1.0railiance-platform2026-08-172027-02-17current
ADR-0002 — S3 owns the placement rule; the package repo owns the numberproposedactive1.0railiance-platform2026-08-172027-02-17current
ADR-0003 — Decisions that bind others live in docs/adr, not only in the State Hubacceptedactive1.0railiance-platform2026-08-172027-02-17current
NetKingdom IAM Profile v0.3acceptedactive0.3net-kingdom2026-07-232027-01-23current
diff --git a/build/publication-manifest.json b/build/publication-manifest.json index 0e5f0a6..9af705c 100644 --- a/build/publication-manifest.json +++ b/build/publication-manifest.json @@ -13,7 +13,7 @@ "source_digest": "99f802d91a0b3a65f0dac58230d8904f7c61cf3f81eff072fbbc59b634612a8a", "source_path": "canon/standards/tenancy-posture_v0.1.md", "source_repo": "net-kingdom", - "source_revision": "0e0962e68b39fdcfb633b5058602174a36416a68", + "source_revision": "ccc2618daee997bb4bd4249613d7c4c7344845cf", "status": "proposed", "title": "NetKingdom Tenancy Posture v0.1" }, @@ -21,16 +21,16 @@ "canonical_path": "architecture/coulomb-estate/v0.1/index.html", "currency": "current", "id": "coulomb-estate-architecture", - "last_reviewed": "2026-08-18", + "last_reviewed": "2026-08-19", "lifecycle": "active", "owner": "the-custodian", - "review_due": "2027-02-18", - "revision": "draft-1", - "revision_path": "architecture/coulomb-estate/v0.1/revisions/draft-1/index.html", - "source_digest": "0ab59ab79931e19615648da435e4a636836904a1189f5b53e3ee8467bea49841", + "review_due": "2027-02-19", + "revision": "draft-2", + "revision_path": "architecture/coulomb-estate/v0.1/revisions/draft-2/index.html", + "source_digest": "4529fad986740aff58f6b5bacd3f86a8852e265714f6e0990cf3c1ab672e3d2e", "source_path": "canon/architecture/coulomb-estate_v0.1.md", "source_repo": "the-custodian", - "source_revision": "5b51623198d9959793762f447f5813960c0b5df8", + "source_revision": "4039c9d1c08c92014ecc0a65dda63cc73ba187bb", "status": "proposed", "title": "Coulomb estate architecture" }, @@ -38,16 +38,16 @@ "canonical_path": "architecture/railiance/v0.1/index.html", "currency": "current", "id": "railiance-architecture", - "last_reviewed": "2026-08-18", + "last_reviewed": "2026-08-19", "lifecycle": "active", "owner": "railiance-master", - "review_due": "2027-02-18", - "revision": "draft-1", - "revision_path": "architecture/railiance/v0.1/revisions/draft-1/index.html", - "source_digest": "1cc0af5cdb6cae771bc134722672385b8e71df1a778adc3358862a1d8f5d7217", + "review_due": "2027-02-19", + "revision": "draft-2", + "revision_path": "architecture/railiance/v0.1/revisions/draft-2/index.html", + "source_digest": "45adb3f484cbeae9423c6f01caae323d545d2d522a6baa24398cbc8ef1a3e974", "source_path": "docs/architecture/railiance_v0.1.md", "source_repo": "railiance-master", - "source_revision": "883533ed8af1703cc9bb4a2b24137e325bbbda47", + "source_revision": "468a52af2b14eba08e05be69c4d2866bfd8d9d7d", "status": "proposed", "title": "Railiance architecture" }, @@ -55,16 +55,16 @@ "canonical_path": "architecture/net-kingdom/v0.1/index.html", "currency": "current", "id": "net-kingdom-architecture", - "last_reviewed": "2026-08-18", + "last_reviewed": "2026-08-19", "lifecycle": "active", "owner": "net-kingdom", - "review_due": "2027-02-18", - "revision": "draft-1", - "revision_path": "architecture/net-kingdom/v0.1/revisions/draft-1/index.html", - "source_digest": "dd42250edcc444fa9a5007c3f9d561984840af2b19a07cf2916cbcc8434df0f7", + "review_due": "2027-02-19", + "revision": "draft-2", + "revision_path": "architecture/net-kingdom/v0.1/revisions/draft-2/index.html", + "source_digest": "3dce1bd24679c8e4ac601e6631b4de18cff7f4cef1e8e79c1a7a0ec0557a0213", "source_path": "docs/architecture/net-kingdom_v0.1.md", "source_repo": "net-kingdom", - "source_revision": "0e0962e68b39fdcfb633b5058602174a36416a68", + "source_revision": "ccc2618daee997bb4bd4249613d7c4c7344845cf", "status": "proposed", "title": "NetKingdom architecture" }, @@ -72,16 +72,16 @@ "canonical_path": "architecture/state-hub/v0.1/index.html", "currency": "current", "id": "state-hub-architecture", - "last_reviewed": "2026-08-18", + "last_reviewed": "2026-08-19", "lifecycle": "active", "owner": "state-hub", - "review_due": "2027-02-18", - "revision": "draft-1", - "revision_path": "architecture/state-hub/v0.1/revisions/draft-1/index.html", - "source_digest": "f65748fa3c861a6f399365ee5315af4e47ec91823837e3d7d89c17d4b385f2aa", + "review_due": "2027-02-19", + "revision": "draft-2", + "revision_path": "architecture/state-hub/v0.1/revisions/draft-2/index.html", + "source_digest": "dd28694239c663324b9753ac0f260cc29419fdf726129898bf42b5e776453074", "source_path": "docs/architecture/state-hub_v0.1.md", "source_repo": "state-hub", - "source_revision": "b606d5d44c6bcb3ff438656acae3bf93a786104b", + "source_revision": "8585bb0c1d0f19e3d55e901e2041edf6aff03f0a", "status": "proposed", "title": "State Hub architecture" }, @@ -98,7 +98,7 @@ "source_digest": "179cbb86bca95f71f46f51ca1971ff1c274eed7d900adf0672b537d4bcc5b480", "source_path": "docs/architecture/policy-nexus_v0.1.md", "source_repo": "policy-nexus", - "source_revision": "64b47d73b9fdf33df535db42c80db3a7435da5cf", + "source_revision": "5cb88edf4d52a65ea31b1f2f53bcf6f71769d234", "status": "proposed", "title": "Policy Nexus architecture" }, @@ -115,7 +115,7 @@ "source_digest": "a28668fb4b8b6c5ec8c94baac000061276d85ef1849ec7ab8d132b913dbfe3be", "source_path": "docs/adr/ADR-0001-addressing-and-permanence.md", "source_repo": "policy-nexus", - "source_revision": "64b47d73b9fdf33df535db42c80db3a7435da5cf", + "source_revision": "5cb88edf4d52a65ea31b1f2f53bcf6f71769d234", "status": "accepted", "title": "Policy addressing and permanence" }, @@ -132,7 +132,7 @@ "source_digest": "b9c993ded8d79d6f871dba9cf08a320b2d619609a448ad3d02b632f5b6f76497", "source_path": "docs/adr/ADR-0001-repository-prefix-architecture.md", "source_repo": "railiance-master", - "source_revision": "883533ed8af1703cc9bb4a2b24137e325bbbda47", + "source_revision": "468a52af2b14eba08e05be69c4d2866bfd8d9d7d", "status": "accepted", "title": "Repository Prefix Architecture" }, @@ -149,7 +149,7 @@ "source_digest": "7e1fc5aedd7294192d8702a22b9f205e5bae20793836fdc48c0c071d10d7ab9d", "source_path": "docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md", "source_repo": "railiance-master", - "source_revision": "883533ed8af1703cc9bb4a2b24137e325bbbda47", + "source_revision": "468a52af2b14eba08e05be69c4d2866bfd8d9d7d", "status": "accepted", "title": "Wave 1 rail-kubernetes Boundary" }, @@ -166,7 +166,7 @@ "source_digest": "28135e94758b6935518d2e83458c1e607deeabb341879b605eef6529b3168cbc", "source_path": "docs/adr/ADR-0003-rapp-first-wave-selection.md", "source_repo": "railiance-master", - "source_revision": "883533ed8af1703cc9bb4a2b24137e325bbbda47", + "source_revision": "468a52af2b14eba08e05be69c4d2866bfd8d9d7d", "status": "accepted", "title": "First-Wave rapp Selection" }, @@ -183,7 +183,7 @@ "source_digest": "36ec3aad5082ceff685d66e091c0a24b52abfc65b36595d00dce2b52a7250f4e", "source_path": "docs/adr/ADR-0004-first-wave-reef-rollout.md", "source_repo": "railiance-master", - "source_revision": "883533ed8af1703cc9bb4a2b24137e325bbbda47", + "source_revision": "468a52af2b14eba08e05be69c4d2866bfd8d9d7d", "status": "accepted", "title": "First-Wave reef Rollout" }, @@ -200,7 +200,7 @@ "source_digest": "e02982ce54691cf1589ac3d04012b9b9282f9eb54ed4b8f2f0544371f9b87f3e", "source_path": "docs/adr/ADR-0005-derived-rail-composition.md", "source_repo": "railiance-master", - "source_revision": "883533ed8af1703cc9bb4a2b24137e325bbbda47", + "source_revision": "468a52af2b14eba08e05be69c4d2866bfd8d9d7d", "status": "accepted", "title": "Derived Rail Composition" }, @@ -217,7 +217,7 @@ "source_digest": "d9fbd9d21d86e461334abc24060c39127f2158ba25317b3d3dc326c4f7eaf08c", "source_path": "docs/adr/ADR-0006-reef-production-admission.md", "source_repo": "railiance-master", - "source_revision": "883533ed8af1703cc9bb4a2b24137e325bbbda47", + "source_revision": "468a52af2b14eba08e05be69c4d2866bfd8d9d7d", "status": "accepted", "title": "Reef Production Admission" }, @@ -234,7 +234,7 @@ "source_digest": "263431f88ba04d6ab9ab3b6c0d6a2bb08634bfe83dc0719350f0855d399c18b2", "source_path": "docs/adr/ADR-0007-rapp-declaration-contract.md", "source_repo": "railiance-master", - "source_revision": "883533ed8af1703cc9bb4a2b24137e325bbbda47", + "source_revision": "468a52af2b14eba08e05be69c4d2866bfd8d9d7d", "status": "accepted", "title": "Rapp Declaration Contract" }, @@ -251,7 +251,7 @@ "source_digest": "276ea38233413f1e23670bbf57c486abc361b0a275ca67efea7d677103713b32", "source_path": "docs/adr/ADR-0008-private-by-default-exposure.md", "source_repo": "railiance-master", - "source_revision": "883533ed8af1703cc9bb4a2b24137e325bbbda47", + "source_revision": "468a52af2b14eba08e05be69c4d2866bfd8d9d7d", "status": "accepted", "title": "Private-by-default Exposure" }, @@ -424,6 +424,227 @@ "source_revision": "35aff380a33f51a512c1e1b42d52d1dc0d95930f", "status": "accepted", "title": "ADR-0005 \u2014 Implement one lane narrowly, route everything else" + }, + { + "canonical_path": "adr/custodian-workplans-as-repo-artefacts/v1/index.html", + "currency": "current", + "id": "CUST-ADR-001", + "last_reviewed": "2026-02-28", + "lifecycle": "active", + "owner": "the-custodian", + "review_due": "2026-08-28", + "revision": "accepted-1", + "revision_path": "adr/custodian-workplans-as-repo-artefacts/v1/revisions/accepted-1/index.html", + "source_digest": "64b11785b683cf21ba2aca18e3b8f3301d6070e6a022df6efc722597a8547334", + "source_path": "canon/architecture/adr-001-workplans-as-repo-artefacts.md", + "source_repo": "the-custodian", + "source_revision": "4039c9d1c08c92014ecc0a65dda63cc73ba187bb", + "status": "accepted", + "title": "Workplans and Work Items Are Repository Artefacts" + }, + { + "canonical_path": "adr/custodian-agent-runtime/v1/index.html", + "currency": "current", + "id": "CUST-ADR-002", + "last_reviewed": "2026-03-12", + "lifecycle": "active", + "owner": "the-custodian", + "review_due": "2026-09-12", + "revision": "accepted-1", + "revision_path": "adr/custodian-agent-runtime/v1/revisions/accepted-1/index.html", + "source_digest": "6aef66cd5cf71a48f5b4e14401dc19a755e2b182445b272d5952df0eb0dea8ec", + "source_path": "canon/architecture/adr-002-custodian-agent-runtime-design.md", + "source_repo": "the-custodian", + "source_revision": "4039c9d1c08c92014ecc0a65dda63cc73ba187bb", + "status": "accepted", + "title": "Custodian Agent Runtime \u2014 v0.1 Bootstrap Design" + }, + { + "canonical_path": "adr/custodian-materialized-derived-state/v1/index.html", + "currency": "current", + "id": "CUST-ADR-003", + "last_reviewed": "2026-03-20", + "lifecycle": "active", + "owner": "the-custodian", + "review_due": "2026-09-20", + "revision": "accepted-1", + "revision_path": "adr/custodian-materialized-derived-state/v1/revisions/accepted-1/index.html", + "source_digest": "350c26d86c573716eb12333473917d91b8cd68b8798197b0077af1a6ba8c6480", + "source_path": "canon/architecture/adr-003-materialized-derived-state.md", + "source_repo": "the-custodian", + "source_revision": "4039c9d1c08c92014ecc0a65dda63cc73ba187bb", + "status": "accepted", + "title": "Materialized Derived State with Fingerprint Invalidation for Repo-Sourced Data" + }, + { + "canonical_path": "adr/custodian-connectivity-first/v1/index.html", + "currency": "current", + "id": "CUST-ADR-004", + "last_reviewed": "2026-03-26", + "lifecycle": "active", + "owner": "the-custodian", + "review_due": "2026-09-26", + "revision": "accepted-1", + "revision_path": "adr/custodian-connectivity-first/v1/revisions/accepted-1/index.html", + "source_digest": "3b68adfa6ab329e73f857cf691dc405136d2d66a0135e2c37c236aabe4659557", + "source_path": "canon/architecture/adr-004-connectivity-first-network-posture.md", + "source_repo": "the-custodian", + "source_revision": "4039c9d1c08c92014ecc0a65dda63cc73ba187bb", + "status": "accepted", + "title": "Connectivity-First Network Posture for Custodian Infrastructure" + }, + { + "canonical_path": "adr/custodian-cross-repo-workplans/v1/index.html", + "currency": "current", + "id": "CUST-ADR-005", + "last_reviewed": "2026-06-22", + "lifecycle": "active", + "owner": "the-custodian", + "review_due": "2026-12-22", + "revision": "accepted-1", + "revision_path": "adr/custodian-cross-repo-workplans/v1/revisions/accepted-1/index.html", + "source_digest": "13195a721d0e579715f5f39ca6f72b5e49c583611e6ca089e6d4618708ae917f", + "source_path": "canon/architecture/adr-005-cross-repo-workplans-project-repos.md", + "source_repo": "the-custodian", + "source_revision": "4039c9d1c08c92014ecc0a65dda63cc73ba187bb", + "status": "accepted", + "title": "Cross-Repo Workplans Live in Dedicated Project Repos" + }, + { + "canonical_path": "adr/custodian-canon-federation/v1/index.html", + "currency": "current", + "id": "CUST-ADR-006", + "last_reviewed": "2026-08-17", + "lifecycle": "active", + "owner": "the-custodian", + "review_due": "2027-02-17", + "revision": "accepted-1", + "revision_path": "adr/custodian-canon-federation/v1/revisions/accepted-1/index.html", + "source_digest": "a454df0e1d227f99ebb36c4abd45c76cc12579086d34f0c0ccfccfd7f4790823", + "source_path": "canon/architecture/adr-006-canon-federation-concept-ownership.md", + "source_repo": "the-custodian", + "source_revision": "4039c9d1c08c92014ecc0a65dda63cc73ba187bb", + "status": "accepted", + "title": "Canon Federation and Concept Ownership Across InfoTech and Commerce" + }, + { + "canonical_path": "adr/custodian-workplan-identity/v1/index.html", + "currency": "current", + "id": "CUST-ADR-007", + "last_reviewed": "2026-08-17", + "lifecycle": "active", + "owner": "the-custodian", + "review_due": "2027-02-17", + "revision": "accepted-1", + "revision_path": "adr/custodian-workplan-identity/v1/revisions/accepted-1/index.html", + "source_digest": "69f463795bdf1769c11415e9c8afa170d6fe62f04a554f7573f269000b5c4b08", + "source_path": "canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md", + "source_repo": "the-custodian", + "source_revision": "4039c9d1c08c92014ecc0a65dda63cc73ba187bb", + "status": "accepted", + "title": "Workplan Identity Uniqueness, Single Registrar, and Repo Worker Topology" + }, + { + "canonical_path": "adr/custodian-hub-authority/v1/index.html", + "currency": "current", + "id": "CUST-ADR-010", + "last_reviewed": "2026-08-17", + "lifecycle": "active", + "owner": "the-custodian", + "review_due": "2027-02-17", + "revision": "draft-1", + "revision_path": "adr/custodian-hub-authority/v1/revisions/draft-1/index.html", + "source_digest": "8ea4448b7729035ae6bee044867ac9fd8b4940ea7013eb2b0256407cba1a0500", + "source_path": "canon/architecture/adr-010-hub-authority-and-local-cache-model.md", + "source_repo": "the-custodian", + "source_revision": "4039c9d1c08c92014ecc0a65dda63cc73ba187bb", + "status": "proposed", + "title": "Hub Authority, Local Cache, and the Two Kinds of Hub Data" + }, + { + "canonical_path": "adr/custodian-federated-namespaces/v1/index.html", + "currency": "current", + "id": "CUST-ADR-011", + "last_reviewed": "2026-08-17", + "lifecycle": "active", + "owner": "the-custodian", + "review_due": "2027-02-17", + "revision": "draft-2", + "revision_path": "adr/custodian-federated-namespaces/v1/revisions/draft-2/index.html", + "source_digest": "f94f429c72f6cfd01ee83f1e5689d2d10ae52d7588d7cbd3ca40aca7eef46fb0", + "source_path": "canon/architecture/adr-011-federated-namespaces-and-reconciliation-limits.md", + "source_repo": "the-custodian", + "source_revision": "4039c9d1c08c92014ecc0a65dda63cc73ba187bb", + "status": "proposed", + "title": "Federated Namespaces: Four Planes, Declared Posture, and the Limits of Reconciliation" + }, + { + "canonical_path": "adr/railiance-s3-platform-service-boundary/v1/index.html", + "currency": "current", + "id": "RPLAT-ADR-0001", + "last_reviewed": "2026-08-17", + "lifecycle": "active", + "owner": "railiance-platform", + "review_due": "2027-02-17", + "revision": "1.0", + "revision_path": "adr/railiance-s3-platform-service-boundary/v1/revisions/1.0/index.html", + "source_digest": "63697581401b53a8437835c2bb8b40f8054cc40d0bc7a2972f83a4a10377f6ba", + "source_path": "docs/adr/ADR-0001-s3-platform-service-boundary.md", + "source_repo": "railiance-platform", + "source_revision": "56d516e10cdad6691f254ec9cb11f11ea364f7de", + "status": "accepted", + "title": "ADR-0001 \u2014 S3 owns platform services, not the substrate beneath them" + }, + { + "canonical_path": "adr/railiance-placement-policy-ownership/v1/index.html", + "currency": "current", + "id": "RPLAT-ADR-0002", + "last_reviewed": "2026-08-17", + "lifecycle": "active", + "owner": "railiance-platform", + "review_due": "2027-02-17", + "revision": "1.0", + "revision_path": "adr/railiance-placement-policy-ownership/v1/revisions/1.0/index.html", + "source_digest": "cfc0ad202c2eeeefd963127ff1defa127c715c001ecc684ab8759733bd8fb9f8", + "source_path": "docs/adr/ADR-0002-placement-policy-ownership.md", + "source_repo": "railiance-platform", + "source_revision": "56d516e10cdad6691f254ec9cb11f11ea364f7de", + "status": "proposed", + "title": "ADR-0002 \u2014 S3 owns the placement rule; the package repo owns the number" + }, + { + "canonical_path": "adr/railiance-decisions-live-in-the-repo/v1/index.html", + "currency": "current", + "id": "RPLAT-ADR-0003", + "last_reviewed": "2026-08-17", + "lifecycle": "active", + "owner": "railiance-platform", + "review_due": "2027-02-17", + "revision": "1.0", + "revision_path": "adr/railiance-decisions-live-in-the-repo/v1/revisions/1.0/index.html", + "source_digest": "9b12ab6aa0e6f9eba03465782c35d6ff4683b682191599e38f4f9614cde9fa1b", + "source_path": "docs/adr/ADR-0003-decisions-live-in-the-repo.md", + "source_repo": "railiance-platform", + "source_revision": "56d516e10cdad6691f254ec9cb11f11ea364f7de", + "status": "accepted", + "title": "ADR-0003 \u2014 Decisions that bind others live in docs/adr, not only in the State Hub" + }, + { + "canonical_path": "standards/iam-profile/v0.3/index.html", + "currency": "current", + "id": "netkingdom-iam-profile-v0.3", + "last_reviewed": "2026-07-23", + "lifecycle": "active", + "owner": "net-kingdom", + "review_due": "2027-01-23", + "revision": "0.3", + "revision_path": "standards/iam-profile/v0.3/revisions/0.3/index.html", + "source_digest": "6287be08e35ddefc8e93d3b127cd8a1be27dc311b014becdbcfb78c4164faa0a", + "source_path": "canon/standards/iam-profile_v0.3.md", + "source_repo": "net-kingdom", + "source_revision": "ccc2618daee997bb4bd4249613d7c4c7344845cf", + "status": "accepted", + "title": "NetKingdom IAM Profile v0.3" } ], "generated_as_of": "2026-08-19", diff --git a/build/standards/iam-profile/v0.3/index.html b/build/standards/iam-profile/v0.3/index.html new file mode 100644 index 0000000..5be045d --- /dev/null +++ b/build/standards/iam-profile/v0.3/index.html @@ -0,0 +1,319 @@ + + + + +NetKingdom IAM Profile v0.3 + +
netkingdom-iam-profile-v0.3 accepted net-kingdom reviewed 2026-07-23generated from canonical source — do not edit

NetKingdom IAM Profile v0.3

Source: net-kingdom · canon/standards/iam-profile_v0.3.md · ccc2618daee997bb4bd4249613d7c4c7344845cf

Review due: 2027-01-23

Minor version. Per ADR-0011's versioning rule, this adds an optional claim and clarifies non-normative guidance — no required claim, validation rule, or previously-issued token is invalidated. Existing v0.2 implementations remain conformant; tenant_roles and the revised Tenant Claim guidance are additive.

+

Purpose

+

The NetKingdom IAM Profile is the provider-neutral OIDC contract that identity implementations issue and applications consume.

+

It defines:

+
  • OIDC discovery and endpoint requirements;
  • Authorization Code + PKCE for human login;
  • service-account and workload identity token requirements;
  • human, service, and agent principal representation;
  • tenant, tenant-grouping, and platform-boundary claims;
  • tenant capability roles and their carrying mechanism;
  • explicit assurance evidence;
  • the identity-to-authorization claim contract consumed by flex-auth;
  • local-development and emergency-access behavior;
  • executable conformance expectations.
+

Applications target this profile, not a concrete identity provider. key-cape is the lightweight implementation. Keycloak is the expanded-mode implementation. Both are interchangeable at the application and authorization boundary when they conform to this document.

+
+

Ownership

+

NetKingdom owns the core/platform profile. See ADR-0011.

+

Downstream systems may define extension scopes, roles, resource names, and tenant policy vocabularies. Those extensions are not part of the core profile unless a future version explicitly adopts them. Extension vocabularies must map back to the core claims in this document before flex-auth or applications consume them.

+
+

Design Principles

+
  • Consumers trust signed OIDC tokens, not provider-specific sessions.
  • Identity providers assert identity and authentication evidence; they do not make final resource authorization decisions.
  • The same profile works in lightweight key-cape mode and expanded Keycloak mode.
  • Tenancy is explicit. tenant:platform is distinct from tenant planes such as tenant:coulomb and from later tenants grouped per ADR-0013.
  • A tenant's onboarding grouping (ADR-0013) and its capability roles (ADR-0014) are independent axes. Neither is encoded in the other; a tenant's roles may change without renaming its identifier.
  • Human, service, and agent principals are distinguishable.
  • Assurance evidence is explicit enough for flex-auth policy.
  • Local-development issuers are useful but never accepted by production.
  • Emergency access is auditable, time-bounded, and reviewable.
+
+

Discovery Contract

+

Every IAM Profile implementation MUST expose OIDC discovery at:

+
GET <issuer>/.well-known/openid-configuration
+

The discovery response MUST include:

+
FieldRequirement
issuerExact issuer identifier used in tokens
authorization_endpointRequired for human Authorization Code + PKCE
token_endpointRequired for token exchange and service accounts
jwks_uriRequired for signature validation
userinfo_endpointRequired when userinfo is supported by the flow
scopes_supportedMUST include openid; SHOULD include profile and email
response_types_supportedMUST include code
grant_types_supportedMUST include authorization_code; MUST include client_credentials or a documented workload-token exchange for service identities
id_token_signing_alg_values_supportedMUST include the implementation signing algorithm; RS256 is required for v0.2+ conformance
code_challenge_methods_supportedMUST include S256
+

The response SHOULD include end_session_endpoint where logout is supported and claims_supported listing the core claims below.

+

Consumers MUST discover endpoints and key material from the issuer metadata instead of hardcoding provider-specific paths.

+
+

Required Flows

+

Human Interactive Flow

+

Human users authenticate with Authorization Code + PKCE.

+

Required properties:

+
  • PKCE with S256 is mandatory for browser and CLI clients.
  • Implicit flow is not part of the profile.
  • MFA or equivalent strong assurance is mandatory for privileged, destructive, platform-root, and emergency access in production.
  • Access tokens are short-lived.
  • Refresh tokens are allowed only for trusted clients with explicit rotation and revocation.
+

Service Account Flow

+

Service-to-service traffic uses client credentials or a deployment's documented workload identity token-exchange equivalent.

+

Required properties:

+
  • Service subjects are stable and named for service plus environment.
  • Secrets or workload credentials are delivered through the credential-management standard, not plaintext configuration.
  • Tokens include an audience that identifies the target service.
  • Tokens carry principal_type: service.
  • Service accounts receive only required scopes and roles.
  • Credentials are rotated and never shared between environments.
+

Agent Principal Flow

+

Agents are automation principals that may act autonomously or under delegated authority.

+

Required properties:

+
  • Tokens carry principal_type: agent.
  • Tokens include an agent object with id and mode.
  • agent.mode is autonomous or delegated.
  • Delegated agents MUST identify the delegating actor using actor_sub or an equivalent act.sub claim.
  • Agent tokens MUST carry the tenant they operate within.
  • Agent tokens MUST include assurance evidence for both the agent credential and any delegated human authority when policy needs it.
+
+

Core Claims

+

Access tokens accepted by production consumers MUST provide the following claims after provider mapping or normalization:

+
ClaimTypeMeaning
issstringOIDC issuer URL or issuer identifier
substringStable subject identifier unique within iss
audstring or arrayIntended audience; MUST include the receiving service
expnumberExpiry timestamp
iatnumberIssued-at timestamp
nbfnumberNot-before timestamp, recommended for production tokens
jtistringToken identifier, recommended for audit and replay controls
tenantstringTenant identifier such as tenant:platform or tenant:friendly:binky
principal_typestringhuman, service, or agent
groupsarrayGroup memberships, possibly empty
rolesarrayCoarse identity roles for the subject, possibly empty
scope or scpstring or arrayGranted OAuth scopes
assuranceobjectAuthentication and credential assurance evidence
+

Recommended human claims:

+
ClaimMeaning
preferred_usernameHuman-readable username
emailContact identity
nameDisplay name
+

Recommended service claims:

+
ClaimMeaning
azp or client_idAuthorized client/service identifier
serviceObject naming the service and environment
+

Recommended agent claims:

+
ClaimMeaning
agent.idStable agent identifier
agent.modeautonomous or delegated
actor_sub or act.subDelegating subject for delegated agents
+

Optional claims (new in v0.3):

+
ClaimTypeMeaning
tenant_rolesarrayCached tenant capability roles (PLTF/IAM/VEN/CUS), possibly empty. See "Tenant Roles" below — this is a point-in-time cache, not the authoritative source.
+

Role Claim

+

The canonical subject-level role claim is roles, an array of strings. This is distinct from tenant_roles (below) — a subject's own coarse identity roles are not the same fact as which capability roles the subject's tenant holds.

+

Expanded-mode Keycloak deployments may also expose provider-native roles such as realm_access.roles, but conforming tokens consumed by flex-auth or applications MUST either emit roles directly or pass through a normalizing adapter that produces roles.

+

Scope Vocabulary

+

The core profile defines only OAuth/OIDC base scopes:

+
ScopeMeaning
openidRequired for OIDC login
profileBasic profile claims
emailEmail claim where appropriate
offline_accessRefresh-token capable access where explicitly allowed
+

Hub-, application-, and resource-specific scopes such as hub:*, ops:*, fin:*, or storage actions are downstream extensions. They are valid only when the consuming system defines them and maps them to flex-auth resource/action semantics.

+
+

Tenant Claim

+

tenant is required for every token accepted by profile consumers.

+

Tenant identifiers follow tenant:<grouping>:<name>, where <grouping> is one of the taxonomy ratified by ADR-0013:

+
trial        - test/trial/showcase tenants only
+friendly     - known, easily reached, tolerant of experimentation/instability
+single       - one-person business entities (freelance consultants)
+small        - up to 10 employees at time of onboarding (attoo)
+medium       - up to 100 employees (attoo)
+large        - up to 1000 employees (attoo)
+enterprise   - 1001+ employees (attoo)
+consumer     - private individuals
+family       - a legal family
+community    - a non-legal group of people
+association  - a legal association of people
+agentic      - financially enabled AI entities
+

tenant:platform and tenant:coulomb remain reserved, ungrouped identifiers outside this taxonomy: tenant:platform is the platform control-plane tenant, not a business entity being onboarded; tenant:coulomb is the first internal/reference tenant established by ADR-0006, predating this taxonomy. Tenant administration for tenant:coulomb or any grouped tenant must never imply platform-root authority.

+

Subjects may have access to multiple tenants, but a token used for a request MUST identify the tenant context for that request. If a client needs to switch tenant context, it obtains a new token or uses an approved token-exchange flow that records the target tenant.

+

The grouping segment is onboarding-risk / entity-shape classification only. It does not gate which capability roles (below) a tenant may hold — see Tenant Roles.

+
+

Tenant Roles

+

Tenant capability roles are a separate fact from the grouping above and from the subject-level roles claim: PLTF, IAM, VEN, CUS (ratified by ADR-0014), non-exclusive — a tenant may hold several simultaneously, and holding one does not require or restrict any grouping.

+

Source of truth: tenant-engine (canon/standards/tenant-engine-boundary-contract_v0.1.md), not this profile and not any token. tenant-engine records role grants/revocations, their link (if any) to a plan/subscription, and emits domain events on change.

+

Carrying mechanism — hybrid, not claim-only:

+
  • key-cape (or Keycloak) MAY stamp a cached tenant_roles claim onto an issued token at issuance time, sourced from tenant-engine.
  • Consumers MAY trust the cached claim for ordinary, non-privileged decisions.
  • Consumers MUST NOT trust the cached claim for privileged, destructive, platform-root, secret, credential-vending, or otherwise assurance.level >= aal2-class decisions. Those decisions MUST query tenant-engine live for current role state before authorizing the action.
  • This bounds staleness for ordinary actions to the issuing token's lifetime (5-30 minutes for service/agent tokens, see Token Lifecycle) while guaranteeing freshness exactly where a stale grant (e.g. VEN surviving a plan cancellation) would matter most.
+

trial-grouped tenants may hold any capability role without restriction — the grouping exists to showcase, test, and explore every role. Safety for trial tenants is enforced through tenant-engine-owned resource guardrails (spend limits, entity/action counts — reserved, not yet specified), not through role gating.

+
+

Assurance Evidence

+

The canonical assurance claim is assurance.

+

It is an object with these fields:

+
FieldTypeMeaning
levelstringaal0, aal1, aal2, aal3, or break_glass
methodsarrayAuthentication methods, e.g. pwd, otp, webauthn, client_secret, workload_identity, upstream_mfa
mfabooleanWhether the authentication included multiple factors or equivalent upstream evidence
sourcestringProvider of the evidence, e.g. key-cape, keycloak, privacyidea, entra, local-identity
atnumberAuthentication time, recommended
+

Level meanings:

+
LevelMeaning
aal0Local/dev or unauthenticated bootstrap evidence; never production privileged
aal1Single-factor or service credential evidence
aal2MFA or equivalent strong upstream assurance
aal3Phishing-resistant or hardware-backed assurance
break_glassTime-bounded emergency access with post-event review
+

Privileged, destructive, platform-root, secret, credential-vending, and emergency flows require aal2 or stronger unless a policy explicitly permits a narrower service or workload identity path. Emergency access MUST use break_glass and short token lifetimes. This is the same threshold class that gates when tenant_roles MUST be re-validated live against tenant-engine rather than trusted from the token — see Tenant Roles.

+

Provider-native claims such as acr and amr may be present, but consumers use assurance as the normalized profile claim.

+
+

Identity To Authorization Contract

+

flex-auth consumes IAM Profile tokens as normative identity input. flex-auth MUST NOT re-derive identity, tenant, group, role, or assurance facts from provider-specific session state.

+

The profile guarantees these inputs for authorization decision envelopes:

+
Decision inputSource claim
Subjectsub
Issueriss
Audienceaud
Tenanttenant
Principal typeprincipal_type
Groupsgroups
Subject rolesroles
Tenant capability rolestenant_roles (cached); tenant-engine live lookup required for high-stakes decisions
Scopesscope or scp
Assuranceassurance
Authorized clientazp or client_id, where present
Agent/delegation contextagent, actor_sub, or act, where present
Token lifetime/audit idsiat, nbf, exp, jti, where present
+

Authorization decisions are made by flex-auth and its delegated PDP adapters. Identity providers may assert roles or scopes, but those claims are inputs to policy, not final permission to act on a resource.

+
+

Token Lifecycle

+

Recommended production defaults:

+
TokenLifetimeNotes
Human access token5-15 minutesShort-lived bearer token
Refresh token8-12 hoursRotated and revoked on logout or suspicion
Service token5-30 minutesReissued by client credentials or workload identity
Agent token5-30 minutesShorter when delegated or platform-scoped
Emergency token5-15 minutesRequires incident/review record
+

Consumers MUST reject expired tokens and tokens with invalid issuer, audience, signature, nbf, or algorithm. Clock skew tolerance SHOULD be small, normally no more than 60 seconds.

+

JWKS material may be cached, but consumers MUST tolerate key rotation by refreshing JWKS when a token uses an unknown kid.

+
+

Local Development Profile

+

A local file-backed provider may be used for development, tests, and bootstrap contexts where the full platform is unavailable.

+

It MUST:

+
  • expose OIDC discovery;
  • issue signed JWTs;
  • support deterministic test users and service accounts;
  • use local-only issuer URLs or a clearly local issuer identifier;
  • mark tokens as local/development through issuer, audience, or assurance evidence;
  • be rejected by production consumers.
+

Production consumers MUST reject:

+
  • issuer local-identity;
  • http:// issuers;
  • loopback issuers such as localhost or 127.0.0.1;
  • tokens with assurance.level: aal0;
  • tokens where the environment marks the issuer as local/dev.
+
+

Emergency And Break-Glass Access

+

Emergency access is allowed only as a break-glass path.

+

Requirements:

+
  • Emergency identities are disabled by default.
  • Activation requires an incident, decision, or human-recorded review reference.
  • Tokens are short-lived and carry the emergency role.
  • Tokens carry assurance.level: break_glass.
  • Every emergency action emits an audit/progress/incident event.
  • Emergency access is reviewed after use and then disabled again.
+

Emergency access MUST NOT bypass audit logging or flex-auth policy.

+
+

Conformance

+

An implementation conforms to IAM Profile v0.3 when it passes the executable conformance suite in:

+
tools/iam-profile-conformance/
+

The suite validates:

+
  • discovery document completeness;
  • PKCE S256 advertisement and rejection of authorization requests that omit a code challenge;
  • JWKS structure and key ids;
  • token issuer, audience, expiry, nbf, iat, and RS256 signature;
  • tenant, principal type, groups, roles, scopes, and assurance claim shape;
  • tenant_roles claim shape when present (array of ratified role strings);
  • agent and delegated-agent claim shape;
  • local-development issuer rejection in production mode.
+

Conformance must be runnable against both key-cape lightweight issuers and Keycloak expanded-mode issuers. Implementations may add provider adapters, but the token consumed by applications and flex-auth must match the core claim contract above. tenant_roles conformance does not require an implementation to emit the claim (it is optional); when emitted, it must match the ratified vocabulary.

+
+

Validation Checklist

+

A service or implementation is profile-ready when:

+
  • it reads OIDC discovery rather than hardcoding endpoints;
  • it validates issuer, audience, expiry, nbf, algorithm, and signature;
  • it refreshes JWKS on unknown kid;
  • it supports Authorization Code + PKCE for human login;
  • it supports service-account or workload identity tokens;
  • it emits tenant, principal_type, groups, roles, scope/scp, and assurance;
  • it uses the ADR-0013 grouping vocabulary for new tenant identifiers;
  • if it consumes tenant_roles, it treats the claim as a cache and re-validates live against tenant-engine before any aal2-class decision;
  • it maps provider-native claims into the canonical core claims;
  • it rejects local-development issuers in production;
  • it logs emergency access with a durable audit trail;
  • flex-auth receives identity facts from the profile, not from provider-specific sessions.
+
netkingdom-iam-profile-v0.3 · · acceptednet-kingdom · canon/standards/iam-profile_v0.3.md · ccc2618daee997bb4bd4249613d7c4c7344845cf
diff --git a/build/standards/iam-profile/v0.3/revisions/0.3/index.html b/build/standards/iam-profile/v0.3/revisions/0.3/index.html new file mode 100644 index 0000000..5be045d --- /dev/null +++ b/build/standards/iam-profile/v0.3/revisions/0.3/index.html @@ -0,0 +1,319 @@ + + + + +NetKingdom IAM Profile v0.3 + +
netkingdom-iam-profile-v0.3 accepted net-kingdom reviewed 2026-07-23generated from canonical source — do not edit

NetKingdom IAM Profile v0.3

Source: net-kingdom · canon/standards/iam-profile_v0.3.md · ccc2618daee997bb4bd4249613d7c4c7344845cf

Review due: 2027-01-23

Minor version. Per ADR-0011's versioning rule, this adds an optional claim and clarifies non-normative guidance — no required claim, validation rule, or previously-issued token is invalidated. Existing v0.2 implementations remain conformant; tenant_roles and the revised Tenant Claim guidance are additive.

+

Purpose

+

The NetKingdom IAM Profile is the provider-neutral OIDC contract that identity implementations issue and applications consume.

+

It defines:

+
  • OIDC discovery and endpoint requirements;
  • Authorization Code + PKCE for human login;
  • service-account and workload identity token requirements;
  • human, service, and agent principal representation;
  • tenant, tenant-grouping, and platform-boundary claims;
  • tenant capability roles and their carrying mechanism;
  • explicit assurance evidence;
  • the identity-to-authorization claim contract consumed by flex-auth;
  • local-development and emergency-access behavior;
  • executable conformance expectations.
+

Applications target this profile, not a concrete identity provider. key-cape is the lightweight implementation. Keycloak is the expanded-mode implementation. Both are interchangeable at the application and authorization boundary when they conform to this document.

+
+

Ownership

+

NetKingdom owns the core/platform profile. See ADR-0011.

+

Downstream systems may define extension scopes, roles, resource names, and tenant policy vocabularies. Those extensions are not part of the core profile unless a future version explicitly adopts them. Extension vocabularies must map back to the core claims in this document before flex-auth or applications consume them.

+
+

Design Principles

+
  • Consumers trust signed OIDC tokens, not provider-specific sessions.
  • Identity providers assert identity and authentication evidence; they do not make final resource authorization decisions.
  • The same profile works in lightweight key-cape mode and expanded Keycloak mode.
  • Tenancy is explicit. tenant:platform is distinct from tenant planes such as tenant:coulomb and from later tenants grouped per ADR-0013.
  • A tenant's onboarding grouping (ADR-0013) and its capability roles (ADR-0014) are independent axes. Neither is encoded in the other; a tenant's roles may change without renaming its identifier.
  • Human, service, and agent principals are distinguishable.
  • Assurance evidence is explicit enough for flex-auth policy.
  • Local-development issuers are useful but never accepted by production.
  • Emergency access is auditable, time-bounded, and reviewable.
+
+

Discovery Contract

+

Every IAM Profile implementation MUST expose OIDC discovery at:

+
GET <issuer>/.well-known/openid-configuration
+

The discovery response MUST include:

+
FieldRequirement
issuerExact issuer identifier used in tokens
authorization_endpointRequired for human Authorization Code + PKCE
token_endpointRequired for token exchange and service accounts
jwks_uriRequired for signature validation
userinfo_endpointRequired when userinfo is supported by the flow
scopes_supportedMUST include openid; SHOULD include profile and email
response_types_supportedMUST include code
grant_types_supportedMUST include authorization_code; MUST include client_credentials or a documented workload-token exchange for service identities
id_token_signing_alg_values_supportedMUST include the implementation signing algorithm; RS256 is required for v0.2+ conformance
code_challenge_methods_supportedMUST include S256
+

The response SHOULD include end_session_endpoint where logout is supported and claims_supported listing the core claims below.

+

Consumers MUST discover endpoints and key material from the issuer metadata instead of hardcoding provider-specific paths.

+
+

Required Flows

+

Human Interactive Flow

+

Human users authenticate with Authorization Code + PKCE.

+

Required properties:

+
  • PKCE with S256 is mandatory for browser and CLI clients.
  • Implicit flow is not part of the profile.
  • MFA or equivalent strong assurance is mandatory for privileged, destructive, platform-root, and emergency access in production.
  • Access tokens are short-lived.
  • Refresh tokens are allowed only for trusted clients with explicit rotation and revocation.
+

Service Account Flow

+

Service-to-service traffic uses client credentials or a deployment's documented workload identity token-exchange equivalent.

+

Required properties:

+
  • Service subjects are stable and named for service plus environment.
  • Secrets or workload credentials are delivered through the credential-management standard, not plaintext configuration.
  • Tokens include an audience that identifies the target service.
  • Tokens carry principal_type: service.
  • Service accounts receive only required scopes and roles.
  • Credentials are rotated and never shared between environments.
+

Agent Principal Flow

+

Agents are automation principals that may act autonomously or under delegated authority.

+

Required properties:

+
  • Tokens carry principal_type: agent.
  • Tokens include an agent object with id and mode.
  • agent.mode is autonomous or delegated.
  • Delegated agents MUST identify the delegating actor using actor_sub or an equivalent act.sub claim.
  • Agent tokens MUST carry the tenant they operate within.
  • Agent tokens MUST include assurance evidence for both the agent credential and any delegated human authority when policy needs it.
+
+

Core Claims

+

Access tokens accepted by production consumers MUST provide the following claims after provider mapping or normalization:

+
ClaimTypeMeaning
issstringOIDC issuer URL or issuer identifier
substringStable subject identifier unique within iss
audstring or arrayIntended audience; MUST include the receiving service
expnumberExpiry timestamp
iatnumberIssued-at timestamp
nbfnumberNot-before timestamp, recommended for production tokens
jtistringToken identifier, recommended for audit and replay controls
tenantstringTenant identifier such as tenant:platform or tenant:friendly:binky
principal_typestringhuman, service, or agent
groupsarrayGroup memberships, possibly empty
rolesarrayCoarse identity roles for the subject, possibly empty
scope or scpstring or arrayGranted OAuth scopes
assuranceobjectAuthentication and credential assurance evidence
+

Recommended human claims:

+
ClaimMeaning
preferred_usernameHuman-readable username
emailContact identity
nameDisplay name
+

Recommended service claims:

+
ClaimMeaning
azp or client_idAuthorized client/service identifier
serviceObject naming the service and environment
+

Recommended agent claims:

+
ClaimMeaning
agent.idStable agent identifier
agent.modeautonomous or delegated
actor_sub or act.subDelegating subject for delegated agents
+

Optional claims (new in v0.3):

+
ClaimTypeMeaning
tenant_rolesarrayCached tenant capability roles (PLTF/IAM/VEN/CUS), possibly empty. See "Tenant Roles" below — this is a point-in-time cache, not the authoritative source.
+

Role Claim

+

The canonical subject-level role claim is roles, an array of strings. This is distinct from tenant_roles (below) — a subject's own coarse identity roles are not the same fact as which capability roles the subject's tenant holds.

+

Expanded-mode Keycloak deployments may also expose provider-native roles such as realm_access.roles, but conforming tokens consumed by flex-auth or applications MUST either emit roles directly or pass through a normalizing adapter that produces roles.

+

Scope Vocabulary

+

The core profile defines only OAuth/OIDC base scopes:

+
ScopeMeaning
openidRequired for OIDC login
profileBasic profile claims
emailEmail claim where appropriate
offline_accessRefresh-token capable access where explicitly allowed
+

Hub-, application-, and resource-specific scopes such as hub:*, ops:*, fin:*, or storage actions are downstream extensions. They are valid only when the consuming system defines them and maps them to flex-auth resource/action semantics.

+
+

Tenant Claim

+

tenant is required for every token accepted by profile consumers.

+

Tenant identifiers follow tenant:<grouping>:<name>, where <grouping> is one of the taxonomy ratified by ADR-0013:

+
trial        - test/trial/showcase tenants only
+friendly     - known, easily reached, tolerant of experimentation/instability
+single       - one-person business entities (freelance consultants)
+small        - up to 10 employees at time of onboarding (attoo)
+medium       - up to 100 employees (attoo)
+large        - up to 1000 employees (attoo)
+enterprise   - 1001+ employees (attoo)
+consumer     - private individuals
+family       - a legal family
+community    - a non-legal group of people
+association  - a legal association of people
+agentic      - financially enabled AI entities
+

tenant:platform and tenant:coulomb remain reserved, ungrouped identifiers outside this taxonomy: tenant:platform is the platform control-plane tenant, not a business entity being onboarded; tenant:coulomb is the first internal/reference tenant established by ADR-0006, predating this taxonomy. Tenant administration for tenant:coulomb or any grouped tenant must never imply platform-root authority.

+

Subjects may have access to multiple tenants, but a token used for a request MUST identify the tenant context for that request. If a client needs to switch tenant context, it obtains a new token or uses an approved token-exchange flow that records the target tenant.

+

The grouping segment is onboarding-risk / entity-shape classification only. It does not gate which capability roles (below) a tenant may hold — see Tenant Roles.

+
+

Tenant Roles

+

Tenant capability roles are a separate fact from the grouping above and from the subject-level roles claim: PLTF, IAM, VEN, CUS (ratified by ADR-0014), non-exclusive — a tenant may hold several simultaneously, and holding one does not require or restrict any grouping.

+

Source of truth: tenant-engine (canon/standards/tenant-engine-boundary-contract_v0.1.md), not this profile and not any token. tenant-engine records role grants/revocations, their link (if any) to a plan/subscription, and emits domain events on change.

+

Carrying mechanism — hybrid, not claim-only:

+
  • key-cape (or Keycloak) MAY stamp a cached tenant_roles claim onto an issued token at issuance time, sourced from tenant-engine.
  • Consumers MAY trust the cached claim for ordinary, non-privileged decisions.
  • Consumers MUST NOT trust the cached claim for privileged, destructive, platform-root, secret, credential-vending, or otherwise assurance.level >= aal2-class decisions. Those decisions MUST query tenant-engine live for current role state before authorizing the action.
  • This bounds staleness for ordinary actions to the issuing token's lifetime (5-30 minutes for service/agent tokens, see Token Lifecycle) while guaranteeing freshness exactly where a stale grant (e.g. VEN surviving a plan cancellation) would matter most.
+

trial-grouped tenants may hold any capability role without restriction — the grouping exists to showcase, test, and explore every role. Safety for trial tenants is enforced through tenant-engine-owned resource guardrails (spend limits, entity/action counts — reserved, not yet specified), not through role gating.

+
+

Assurance Evidence

+

The canonical assurance claim is assurance.

+

It is an object with these fields:

+
FieldTypeMeaning
levelstringaal0, aal1, aal2, aal3, or break_glass
methodsarrayAuthentication methods, e.g. pwd, otp, webauthn, client_secret, workload_identity, upstream_mfa
mfabooleanWhether the authentication included multiple factors or equivalent upstream evidence
sourcestringProvider of the evidence, e.g. key-cape, keycloak, privacyidea, entra, local-identity
atnumberAuthentication time, recommended
+

Level meanings:

+
LevelMeaning
aal0Local/dev or unauthenticated bootstrap evidence; never production privileged
aal1Single-factor or service credential evidence
aal2MFA or equivalent strong upstream assurance
aal3Phishing-resistant or hardware-backed assurance
break_glassTime-bounded emergency access with post-event review
+

Privileged, destructive, platform-root, secret, credential-vending, and emergency flows require aal2 or stronger unless a policy explicitly permits a narrower service or workload identity path. Emergency access MUST use break_glass and short token lifetimes. This is the same threshold class that gates when tenant_roles MUST be re-validated live against tenant-engine rather than trusted from the token — see Tenant Roles.

+

Provider-native claims such as acr and amr may be present, but consumers use assurance as the normalized profile claim.

+
+

Identity To Authorization Contract

+

flex-auth consumes IAM Profile tokens as normative identity input. flex-auth MUST NOT re-derive identity, tenant, group, role, or assurance facts from provider-specific session state.

+

The profile guarantees these inputs for authorization decision envelopes:

+
Decision inputSource claim
Subjectsub
Issueriss
Audienceaud
Tenanttenant
Principal typeprincipal_type
Groupsgroups
Subject rolesroles
Tenant capability rolestenant_roles (cached); tenant-engine live lookup required for high-stakes decisions
Scopesscope or scp
Assuranceassurance
Authorized clientazp or client_id, where present
Agent/delegation contextagent, actor_sub, or act, where present
Token lifetime/audit idsiat, nbf, exp, jti, where present
+

Authorization decisions are made by flex-auth and its delegated PDP adapters. Identity providers may assert roles or scopes, but those claims are inputs to policy, not final permission to act on a resource.

+
+

Token Lifecycle

+

Recommended production defaults:

+
TokenLifetimeNotes
Human access token5-15 minutesShort-lived bearer token
Refresh token8-12 hoursRotated and revoked on logout or suspicion
Service token5-30 minutesReissued by client credentials or workload identity
Agent token5-30 minutesShorter when delegated or platform-scoped
Emergency token5-15 minutesRequires incident/review record
+

Consumers MUST reject expired tokens and tokens with invalid issuer, audience, signature, nbf, or algorithm. Clock skew tolerance SHOULD be small, normally no more than 60 seconds.

+

JWKS material may be cached, but consumers MUST tolerate key rotation by refreshing JWKS when a token uses an unknown kid.

+
+

Local Development Profile

+

A local file-backed provider may be used for development, tests, and bootstrap contexts where the full platform is unavailable.

+

It MUST:

+
  • expose OIDC discovery;
  • issue signed JWTs;
  • support deterministic test users and service accounts;
  • use local-only issuer URLs or a clearly local issuer identifier;
  • mark tokens as local/development through issuer, audience, or assurance evidence;
  • be rejected by production consumers.
+

Production consumers MUST reject:

+
  • issuer local-identity;
  • http:// issuers;
  • loopback issuers such as localhost or 127.0.0.1;
  • tokens with assurance.level: aal0;
  • tokens where the environment marks the issuer as local/dev.
+
+

Emergency And Break-Glass Access

+

Emergency access is allowed only as a break-glass path.

+

Requirements:

+
  • Emergency identities are disabled by default.
  • Activation requires an incident, decision, or human-recorded review reference.
  • Tokens are short-lived and carry the emergency role.
  • Tokens carry assurance.level: break_glass.
  • Every emergency action emits an audit/progress/incident event.
  • Emergency access is reviewed after use and then disabled again.
+

Emergency access MUST NOT bypass audit logging or flex-auth policy.

+
+

Conformance

+

An implementation conforms to IAM Profile v0.3 when it passes the executable conformance suite in:

+
tools/iam-profile-conformance/
+

The suite validates:

+
  • discovery document completeness;
  • PKCE S256 advertisement and rejection of authorization requests that omit a code challenge;
  • JWKS structure and key ids;
  • token issuer, audience, expiry, nbf, iat, and RS256 signature;
  • tenant, principal type, groups, roles, scopes, and assurance claim shape;
  • tenant_roles claim shape when present (array of ratified role strings);
  • agent and delegated-agent claim shape;
  • local-development issuer rejection in production mode.
+

Conformance must be runnable against both key-cape lightweight issuers and Keycloak expanded-mode issuers. Implementations may add provider adapters, but the token consumed by applications and flex-auth must match the core claim contract above. tenant_roles conformance does not require an implementation to emit the claim (it is optional); when emitted, it must match the ratified vocabulary.

+
+

Validation Checklist

+

A service or implementation is profile-ready when:

+
  • it reads OIDC discovery rather than hardcoding endpoints;
  • it validates issuer, audience, expiry, nbf, algorithm, and signature;
  • it refreshes JWKS on unknown kid;
  • it supports Authorization Code + PKCE for human login;
  • it supports service-account or workload identity tokens;
  • it emits tenant, principal_type, groups, roles, scope/scp, and assurance;
  • it uses the ADR-0013 grouping vocabulary for new tenant identifiers;
  • if it consumes tenant_roles, it treats the claim as a cache and re-validates live against tenant-engine before any aal2-class decision;
  • it maps provider-native claims into the canonical core claims;
  • it rejects local-development issuers in production;
  • it logs emergency access with a durable audit trail;
  • flex-auth receives identity facts from the profile, not from provider-specific sessions.
+
netkingdom-iam-profile-v0.3 · · acceptednet-kingdom · canon/standards/iam-profile_v0.3.md · ccc2618daee997bb4bd4249613d7c4c7344845cf
diff --git a/build/standards/tenancy-posture/v0.1/index.html b/build/standards/tenancy-posture/v0.1/index.html index b7b0384..0ae1375 100644 --- a/build/standards/tenancy-posture/v0.1/index.html +++ b/build/standards/tenancy-posture/v0.1/index.html @@ -1,6 +1,6 @@ - + NetKingdom Tenancy Posture v0.1 -
netkingdom-tenancy-posture proposed · draft-8 net-kingdom reviewed 2026-08-17generated from canonical source — do not edit

NetKingdom Tenancy Posture v0.1

A framework for describing, holding and improving multi-tenancy — including where we are not there yet.

Source: net-kingdom · canon/standards/tenancy-posture_v0.1.md · 0e0962e68b39fdcfb633b5058602174a36416a68

Review due: 2027-02-17

Status

+
netkingdom-tenancy-posture proposed · draft-8 net-kingdom reviewed 2026-08-17generated from canonical source — do not edit

NetKingdom Tenancy Posture v0.1

A framework for describing, holding and improving multi-tenancy — including where we are not there yet.

Source: net-kingdom · canon/standards/tenancy-posture_v0.1.md · ccc2618daee997bb4bd4249613d7c4c7344845cf

Review due: 2027-02-17

Status

Proposed, draft-8; ratification-ready. Relocated from the-custodian/canon/architecture on 2026-08-17: multi-tenancy is part of the IT-security framework NetKingdom provides, so this framework belongs in NetKingdom canon beside the IAM Profile and the tenant-engine boundary contract, not in the work-factory canon.

  • draft-1 proposed a single model with fixed characteristics. Rejected: it could not describe a repo that is not there yet.
  • draft-2 reframed to graduated levels per axis. Externally corroborated (§16), but four of its statements were wrong and one thing it needed was missing.
  • draft-3 applied those corrections, added the retention axis, and recorded an adoption stance.
  • draft-4 closed the two gaps draft-3 left open: R4 had no mechanism beyond waiting, and the noisy-neighbour evidence artifact asserted something shared infrastructure cannot provide.
  • draft-5 relocated to NetKingdom and renamed the dimensions from planes to axes, because the word was already taken (§0).
  • draft-6 applied tenant-engine's review: five changes, including an axis that did not fit its data shape.
  • draft-7 applies audit-core, railiance-platform and flex-auth. Eleven further changes, two of them corrections to statements this document made as fact about other repos. Every posture I guessed was too generous, on every repo that has now self-reported.
  • draft-8 applies adaptive-pricing's review, the last of the six, and the consistency review across all declarations. It adds the missing availability axis, a canonical declaration schema, explicit authority for tier assurance, retention/placement coupling, downgrade propagation, and honest sanctioned customer language. It also corrects the distinction between an implemented control and an evidenced current level.

Reviewed by all six. The score: six repos found three live defects in their own code by reading the ladders — tenant-engine's unfiltered event accessor, audit-core's unfiltered read path, flex-auth's unauthenticated /v1/check — and railiance-platform found apps-pg running with no backup configured at all while writing its §10.2 disclosure. The framework changed to fit the repos; no repo was told to fabricate a posture.

@@ -441,4 +441,4 @@ per consumer: 14 connections (12 runtime + 2 migration)

20Ratification path

  1. Reviewed by tenant-engine, flex-auth, audit-core, rapp-postgres, railiance-platform and adaptive-pricing against §19. Complete in draft-8.
  2. Each publishes its own posture vector (§5) as part of review. The framework is validated by whether it can describe them accurately — if a repo cannot express itself in these six ladders, the ladders are wrong and this document changes, not the repo. Complete in draft-8; all six root declarations validate against the canonical schema.
  3. On acceptance, supersedes the routing of rapp-postgres/docs/canon-drafts/shared-platform-relational-storage_v0.1-draft.md, whose §§3–8 are absorbed here. That draft is withdrawn rather than left pending.
  4. On acceptance, rapp-postgres ADR-0001 through ADR-0004 move to accepted and are annotated as the PostgreSQL implementation of the E, P, R and shared-capacity rules.
-
netkingdom-tenancy-posture · draft-8 · proposednet-kingdom · canon/standards/tenancy-posture_v0.1.md · 0e0962e68b39fdcfb633b5058602174a36416a68
+
diff --git a/docs/adr-review/SUMMARY.md b/docs/adr-review/SUMMARY.md index 7be34e8..7028803 100644 --- a/docs/adr-review/SUMMARY.md +++ b/docs/adr-review/SUMMARY.md @@ -1,30 +1,29 @@ # ADR review ledger summary -Rows: 136 +Rows: 144 ## Inventory dispositions - `excluded`: 3 -- `metadata-pending`: 100 -- `published`: 25 -- `unsupported-format`: 8 +- `metadata-pending`: 93 +- `published`: 38 +- `unsupported-format`: 10 ## Proposed dispositions - `conflict`: 5 -- `publish`: 32 +- `local`: 36 +- `publish`: 82 - `superseded`: 5 -- `unreviewed`: 94 +- `unreviewed`: 16 ## Front-matter `id` collisions -- `ADR-001`: coulomb-loop/docs/adr/ADR-001-workplan-prefix.md, kaizen-agentic/docs/adr/ADR-001-workplan-convention.md, rein-aharness/docs/adr/ADR-001-agent-harness-architecture.md, the-custodian/canon/architecture/adr-001-workplans-as-repo-artefacts.md -- `ADR-002`: coulomb-loop/docs/adr/ADR-002-customer-supplier-boundary.md, kaizen-agentic/docs/adr/ADR-002-project-memory-convention.md, the-custodian/canon/architecture/adr-002-custodian-agent-runtime-design.md -- `ADR-003`: coulomb-loop/docs/adr/ADR-003-cadence-ramp-policy.md, kaizen-agentic/docs/adr/ADR-003-protocols-artifact-convention.md, the-custodian/canon/architecture/adr-003-materialized-derived-state.md -- `ADR-004`: coulomb-loop/docs/adr/ADR-004-repo-rotation-on-diminishing-returns.md, kaizen-agentic/docs/adr/ADR-004-project-metrics-convention.md, the-custodian/canon/architecture/adr-004-connectivity-first-network-posture.md +- `ADR-001`: coulomb-loop/docs/adr/ADR-001-workplan-prefix.md, kaizen-agentic/docs/adr/ADR-001-workplan-convention.md, rein-aharness/docs/adr/ADR-001-agent-harness-architecture.md +- `ADR-002`: coulomb-loop/docs/adr/ADR-002-customer-supplier-boundary.md, kaizen-agentic/docs/adr/ADR-002-project-memory-convention.md +- `ADR-003`: coulomb-loop/docs/adr/ADR-003-cadence-ramp-policy.md, kaizen-agentic/docs/adr/ADR-003-protocols-artifact-convention.md +- `ADR-004`: coulomb-loop/docs/adr/ADR-004-repo-rotation-on-diminishing-returns.md, kaizen-agentic/docs/adr/ADR-004-project-metrics-convention.md - `ADR-0001`: coulomb-social/docs/adr/ADR-0001-netkingdom-identity.md, key-cape/docs/adr/ADR-0001-choose-go-for-keycape.md, target-revenue/docs/adr/ADR-0001-stage0-library-stack.md -- `ADR-005`: kaizen-agentic/docs/adr/ADR-005-scheduled-agent-execution.md, the-custodian/canon/architecture/adr-005-cross-repo-workplans-project-repos.md -- `netkingdom-iam-profile`: net-kingdom/canon/standards/iam-profile_v0.2.md, net-kingdom/canon/standards/iam-profile_v0.3.md ## Bare ADR-NNNN collisions diff --git a/docs/adr-review/ledger.json b/docs/adr-review/ledger.json index 45d8bfa..8eb05db 100644 --- a/docs/adr-review/ledger.json +++ b/docs/adr-review/ledger.json @@ -223,8 +223,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Storage address contract.", "source_path": "docs/adr/0001-content-addressed-storage.md", "source_repo": "artifact-store", "successor": "" @@ -257,8 +257,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Event-log SoR.", "source_path": "docs/adr/0002-event-log-source-of-truth.md", "source_repo": "artifact-store", "successor": "" @@ -291,8 +291,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Manifest canonicalisation.", "source_path": "docs/adr/0003-manifest-canonical-cbor.md", "source_repo": "artifact-store", "successor": "" @@ -325,8 +325,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Control/data plane split.", "source_path": "docs/adr/0004-control-plane-data-plane-contract.md", "source_repo": "artifact-store", "successor": "" @@ -359,8 +359,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "local", + "review_notes": "V1 stack preference, not a cross-repo contract.", "source_path": "docs/adr/0005-v1-tech-stack.md", "source_repo": "artifact-store", "successor": "" @@ -393,8 +393,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "OCI reachability constraint.", "source_path": "docs/adr/0006-oci-compatibility-reachable.md", "source_repo": "artifact-store", "successor": "" @@ -427,8 +427,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "local", + "review_notes": "Directory index, not a governing record.", "source_path": "docs/adr/README.md", "source_repo": "artifact-store", "successor": "" @@ -461,8 +461,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "local", + "review_notes": "Client API shape; no cross-repo bind.", "source_path": "docs/adr/001-no-listall-method.md", "source_repo": "binect-js", "successor": "" @@ -503,8 +503,7 @@ }, "id_collisions": [ "kaizen-agentic/docs/adr/ADR-001-workplan-convention.md", - "rein-aharness/docs/adr/ADR-001-agent-harness-architecture.md", - "the-custodian/canon/architecture/adr-001-workplans-as-repo-artefacts.md" + "rein-aharness/docs/adr/ADR-001-agent-harness-architecture.md" ], "inventory_disposition": "metadata-pending", "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", @@ -514,8 +513,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "Front-matter id 'ADR-001' is shared; pick a repo-prefixed publication id before publish. Who rules: owning repo.", + "proposed_disposition": "publish", + "review_notes": "Workplan prefix convention used fleet-wide.", "source_path": "docs/adr/ADR-001-workplan-prefix.md", "source_repo": "coulomb-loop", "successor": "" @@ -553,8 +552,7 @@ "version": "" }, "id_collisions": [ - "kaizen-agentic/docs/adr/ADR-002-project-memory-convention.md", - "the-custodian/canon/architecture/adr-002-custodian-agent-runtime-design.md" + "kaizen-agentic/docs/adr/ADR-002-project-memory-convention.md" ], "inventory_disposition": "metadata-pending", "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", @@ -564,8 +562,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "Front-matter id 'ADR-002' is shared; pick a repo-prefixed publication id before publish. Who rules: owning repo.", + "proposed_disposition": "local", + "review_notes": "Engagement boundary for the loop product.", "source_path": "docs/adr/ADR-002-customer-supplier-boundary.md", "source_repo": "coulomb-loop", "successor": "" @@ -601,8 +599,7 @@ "version": "" }, "id_collisions": [ - "kaizen-agentic/docs/adr/ADR-003-protocols-artifact-convention.md", - "the-custodian/canon/architecture/adr-003-materialized-derived-state.md" + "kaizen-agentic/docs/adr/ADR-003-protocols-artifact-convention.md" ], "inventory_disposition": "metadata-pending", "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", @@ -612,8 +609,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "Front-matter id 'ADR-003' is shared; pick a repo-prefixed publication id before publish. Who rules: owning repo.", + "proposed_disposition": "local", + "review_notes": "Loop cadence policy.", "source_path": "docs/adr/ADR-003-cadence-ramp-policy.md", "source_repo": "coulomb-loop", "successor": "" @@ -648,8 +645,7 @@ "version": "" }, "id_collisions": [ - "kaizen-agentic/docs/adr/ADR-004-project-metrics-convention.md", - "the-custodian/canon/architecture/adr-004-connectivity-first-network-posture.md" + "kaizen-agentic/docs/adr/ADR-004-project-metrics-convention.md" ], "inventory_disposition": "metadata-pending", "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", @@ -659,8 +655,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "Front-matter id 'ADR-004' is shared; pick a repo-prefixed publication id before publish. Who rules: owning repo.", + "proposed_disposition": "local", + "review_notes": "Loop rotation heuristic.", "source_path": "docs/adr/ADR-004-repo-rotation-on-diminishing-returns.md", "source_repo": "coulomb-loop", "successor": "" @@ -711,8 +707,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "Front-matter id 'ADR-0001' is shared; pick a repo-prefixed publication id before publish. Who rules: owning repo.", + "proposed_disposition": "publish", + "review_notes": "Identity choice for the social surface.", "source_path": "docs/adr/ADR-0001-netkingdom-identity.md", "source_repo": "coulomb-social", "successor": "" @@ -804,8 +800,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Content SoR.", "source_path": "docs/adr/ADR-0003-page-centric-markdown-sor.md", "source_repo": "coulomb-social", "successor": "" @@ -846,8 +842,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Content plane upgrades.", "source_path": "docs/adr/ADR-0004-content-plane-thin-git-upgrades.md", "source_repo": "coulomb-social", "successor": "" @@ -896,8 +892,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "local", + "review_notes": "Binder-owned UI surface.", "source_path": "docs/adr/ADR-0001-reference-ui-surface.md", "source_repo": "evidence-binder", "successor": "" @@ -930,8 +926,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Flex-auth implementers consume this.", "source_path": "docs/adr/0001-implementation-language-and-skeleton.md", "source_repo": "flex-auth", "successor": "" @@ -964,8 +960,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Policy format others write.", "source_path": "docs/adr/0002-rego-in-markdown-policy-format.md", "source_repo": "flex-auth", "successor": "" @@ -998,8 +994,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Alignment contract for the evaluator.", "source_path": "docs/adr/0003-topaz-aligned-mvp.md", "source_repo": "flex-auth", "successor": "" @@ -1032,8 +1028,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Caller identity binds every check client.", "source_path": "docs/adr/0004-inbound-caller-authentication.md", "source_repo": "flex-auth", "successor": "" @@ -1082,8 +1078,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Harness family routing.", "source_path": "docs/adr/ADR-001-rein-harness-family.md", "source_repo": "glas-harness", "successor": "" @@ -1130,8 +1126,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "local", + "review_notes": "Partly open; not current governing.", "source_path": "docs/adr/ADR-002-credential-brokering-and-composable-reins.md", "source_repo": "glas-harness", "successor": "" @@ -1176,8 +1172,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Scheduling locality.", "source_path": "docs/adr/ADR-003-scheduling-and-blueprint-sourcing-stay-rein-local.md", "source_repo": "glas-harness", "successor": "" @@ -1221,8 +1217,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "local", + "review_notes": "Explicitly deferred.", "source_path": "docs/adr/ADR-004-composable-reins-stay-deferred.md", "source_repo": "glas-harness", "successor": "" @@ -1263,8 +1259,7 @@ }, "id_collisions": [ "coulomb-loop/docs/adr/ADR-001-workplan-prefix.md", - "rein-aharness/docs/adr/ADR-001-agent-harness-architecture.md", - "the-custodian/canon/architecture/adr-001-workplans-as-repo-artefacts.md" + "rein-aharness/docs/adr/ADR-001-agent-harness-architecture.md" ], "inventory_disposition": "metadata-pending", "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", @@ -1274,8 +1269,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "Front-matter id 'ADR-001' is shared; pick a repo-prefixed publication id before publish. Who rules: owning repo.", + "proposed_disposition": "publish", + "review_notes": "Workplan convention consumed by agents.", "source_path": "docs/adr/ADR-001-workplan-convention.md", "source_repo": "kaizen-agentic", "successor": "" @@ -1313,8 +1308,7 @@ "version": "" }, "id_collisions": [ - "coulomb-loop/docs/adr/ADR-002-customer-supplier-boundary.md", - "the-custodian/canon/architecture/adr-002-custodian-agent-runtime-design.md" + "coulomb-loop/docs/adr/ADR-002-customer-supplier-boundary.md" ], "inventory_disposition": "metadata-pending", "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", @@ -1324,8 +1318,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "Front-matter id 'ADR-002' is shared; pick a repo-prefixed publication id before publish. Who rules: owning repo.", + "proposed_disposition": "local", + "review_notes": "Kaizen project memory.", "source_path": "docs/adr/ADR-002-project-memory-convention.md", "source_repo": "kaizen-agentic", "successor": "" @@ -1361,8 +1355,7 @@ "version": "" }, "id_collisions": [ - "coulomb-loop/docs/adr/ADR-003-cadence-ramp-policy.md", - "the-custodian/canon/architecture/adr-003-materialized-derived-state.md" + "coulomb-loop/docs/adr/ADR-003-cadence-ramp-policy.md" ], "inventory_disposition": "metadata-pending", "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", @@ -1372,8 +1365,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "Front-matter id 'ADR-003' is shared; pick a repo-prefixed publication id before publish. Who rules: owning repo.", + "proposed_disposition": "local", + "review_notes": "Kaizen protocols artifact.", "source_path": "docs/adr/ADR-003-protocols-artifact-convention.md", "source_repo": "kaizen-agentic", "successor": "" @@ -1408,8 +1401,7 @@ "version": "" }, "id_collisions": [ - "coulomb-loop/docs/adr/ADR-004-repo-rotation-on-diminishing-returns.md", - "the-custodian/canon/architecture/adr-004-connectivity-first-network-posture.md" + "coulomb-loop/docs/adr/ADR-004-repo-rotation-on-diminishing-returns.md" ], "inventory_disposition": "metadata-pending", "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", @@ -1419,8 +1411,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "Front-matter id 'ADR-004' is shared; pick a repo-prefixed publication id before publish. Who rules: owning repo.", + "proposed_disposition": "local", + "review_notes": "Kaizen metrics.", "source_path": "docs/adr/ADR-004-project-metrics-convention.md", "source_repo": "kaizen-agentic", "successor": "" @@ -1434,9 +1426,7 @@ "railiance-master/docs/adr/ADR-0005-derived-rail-composition.md", "the-custodian/canon/architecture/adr-005-cross-repo-workplans-project-repos.md" ], - "conflict_kinds": [ - 1 - ], + "conflict_kinds": [], "file_present": true, "frontmatter": { "id": "ADR-005", @@ -1449,9 +1439,7 @@ "updated": "", "version": "" }, - "id_collisions": [ - "the-custodian/canon/architecture/adr-005-cross-repo-workplans-project-repos.md" - ], + "id_collisions": [], "inventory_disposition": "metadata-pending", "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", "missing_fields": [ @@ -1460,8 +1448,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "Front-matter id 'ADR-005' is shared; pick a repo-prefixed publication id before publish. Who rules: owning repo.", + "proposed_disposition": "local", + "review_notes": "Kaizen scheduler.", "source_path": "docs/adr/ADR-005-scheduled-agent-execution.md", "source_repo": "kaizen-agentic", "successor": "" @@ -1498,8 +1486,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "local", + "review_notes": "Kaizen engagement.", "source_path": "docs/adr/ADR-006-customer-engagement-convention.md", "source_repo": "kaizen-agentic", "successor": "" @@ -1536,8 +1524,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "local", + "review_notes": "Kaizen forward-deployed engagement.", "source_path": "docs/adr/ADR-007-forward-deployed-engagement-convention.md", "source_repo": "kaizen-agentic", "successor": "" @@ -1588,8 +1576,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "Front-matter id 'ADR-0001' is shared; pick a repo-prefixed publication id before publish. Who rules: owning repo.", + "proposed_disposition": "local", + "review_notes": "Language choice; audience is this repo.", "source_path": "docs/adr/ADR-0001-choose-go-for-keycape.md", "source_repo": "key-cape", "successor": "" @@ -1638,8 +1626,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "local", + "review_notes": "Implementation storage for debug UI.", "source_path": "docs/adr/ADR-001-client-side-debug-storage.md", "source_repo": "markitect-main", "successor": "" @@ -1686,8 +1674,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "local", + "review_notes": "Product robustness note for Markitect.", "source_path": "docs/adr/ADR-002-robustness-principle-for-production-use.md", "source_repo": "markitect-main", "successor": "" @@ -1720,8 +1708,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Credential standard for implementers.", "source_path": "canon/standards/credential-management_v0.2.md", "source_repo": "net-kingdom", "successor": "" @@ -1736,19 +1724,17 @@ ], "file_present": true, "frontmatter": { - "id": "netkingdom-iam-profile", + "id": "netkingdom-iam-profile-v0.2", "last_reviewed": "", "owner": "", "review_interval": "", "revision": "", - "status": "accepted", + "status": "superseded", "title": "NetKingdom IAM Profile v0.2", "updated": "2026-05-22", "version": "0.2" }, - "id_collisions": [ - "net-kingdom/canon/standards/iam-profile_v0.3.md" - ], + "id_collisions": [], "inventory_disposition": "metadata-pending", "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", "missing_fields": [ @@ -1757,7 +1743,7 @@ ], "notes": "", "proposed_disposition": "superseded", - "review_notes": "v0.3 says it supersedes v0.2, but v0.2 is still status accepted and shares id netkingdom-iam-profile. Who rules: net-kingdom (status + unique id).", + "review_notes": "Status set to superseded; unique id netkingdom-iam-profile-v0.2.", "source_path": "canon/standards/iam-profile_v0.2.md", "source_repo": "net-kingdom", "successor": "net-kingdom/canon/standards/iam-profile_v0.3.md" @@ -1771,28 +1757,23 @@ ], "file_present": true, "frontmatter": { - "id": "netkingdom-iam-profile", - "last_reviewed": "", - "owner": "", - "review_interval": "", + "id": "netkingdom-iam-profile-v0.3", + "last_reviewed": "2026-07-23", + "owner": "net-kingdom", + "review_interval": "6m", "revision": "", "status": "accepted", "title": "NetKingdom IAM Profile v0.3", "updated": "2026-07-23", "version": "0.3" }, - "id_collisions": [ - "net-kingdom/canon/standards/iam-profile_v0.2.md" - ], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "owner", - "review" - ], + "id_collisions": [], + "inventory_disposition": "published", + "inventory_reason": "Published through an explicit publication.json document entry.", + "missing_fields": [], "notes": "", "proposed_disposition": "publish", - "review_notes": "Current IAM profile. Cannot publish until id is unique (e.g. netkingdom-iam-profile-v0.3). Who rules: net-kingdom.", + "review_notes": "Id now netkingdom-iam-profile-v0.3; ready to publish.", "source_path": "canon/standards/iam-profile_v0.3.md", "source_repo": "net-kingdom", "successor": "" @@ -1821,8 +1802,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Playbook contract.", "source_path": "canon/standards/playbook-capability-contract_v0.1.md", "source_repo": "net-kingdom", "successor": "" @@ -1848,8 +1829,8 @@ "inventory_reason": "Published through an explicit publication.json document entry.", "missing_fields": [], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Already published.", "source_path": "canon/standards/tenancy-posture_v0.1.md", "source_repo": "net-kingdom", "successor": "" @@ -1878,8 +1859,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Tenant-engine boundary.", "source_path": "canon/standards/tenant-engine-boundary-contract_v0.1.md", "source_repo": "net-kingdom", "successor": "" @@ -1908,8 +1889,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "User-engine boundary.", "source_path": "canon/standards/user-engine-boundary-contract_v0.1.md", "source_repo": "net-kingdom", "successor": "" @@ -1946,8 +1927,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Identity architecture others implement.", "source_path": "docs/adr/ADR-0006-recursive-multi-tenant-identity-authorization.md", "source_repo": "net-kingdom", "successor": "" @@ -1984,8 +1965,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Orchestration boundary.", "source_path": "docs/adr/ADR-0007-security-orchestration-boundary.md", "source_repo": "net-kingdom", "successor": "" @@ -2021,8 +2002,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "STS vending boundary.", "source_path": "docs/adr/ADR-0008-object-storage-sts-credential-vending.md", "source_repo": "net-kingdom", "successor": "" @@ -2057,8 +2038,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Orchestration vs dependency.", "source_path": "docs/adr/ADR-0010-orchestration-vs-dependency-self-coherent-intent.md", "source_repo": "net-kingdom", "successor": "" @@ -2093,8 +2074,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "IAM profile ownership.", "source_path": "docs/adr/ADR-0011-iam-profile-ownership-and-version-governance.md", "source_repo": "net-kingdom", "successor": "" @@ -2127,8 +2108,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Playbook ownership.", "source_path": "docs/adr/ADR-0012-playbook-capability-contract-ownership.md", "source_repo": "net-kingdom", "successor": "" @@ -2161,8 +2142,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Onboarding taxonomy.", "source_path": "docs/adr/ADR-0013-tenant-onboarding-grouping-taxonomy.md", "source_repo": "net-kingdom", "successor": "" @@ -2195,8 +2176,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Tenant capability roles.", "source_path": "docs/adr/ADR-0014-tenant-capability-roles-and-tenant-engine-ownership.md", "source_repo": "net-kingdom", "successor": "" @@ -2229,8 +2210,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Workload packaging.", "source_path": "docs/adr/ADR-0015-netkingdom-railiance-workload-packaging-and-relational-platform.md", "source_repo": "net-kingdom", "successor": "" @@ -2242,10 +2223,10 @@ "file_present": true, "frontmatter": { "id": "net-kingdom-architecture", - "last_reviewed": "2026-08-18", + "last_reviewed": "2026-08-19", "owner": "net-kingdom", "review_interval": "6m", - "revision": "draft-1", + "revision": "draft-2", "status": "proposed", "title": "NetKingdom architecture", "updated": "", @@ -2256,8 +2237,8 @@ "inventory_reason": "Published through an explicit publication.json document entry.", "missing_fields": [], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "First-wave stub, published.", "source_path": "docs/architecture/net-kingdom_v0.1.md", "source_repo": "net-kingdom", "successor": "" @@ -2484,8 +2465,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "local", + "review_notes": "Directory index, not a governing record.", "source_path": "docs/adr/README.md", "source_repo": "ops-warden", "successor": "" @@ -2554,8 +2535,8 @@ "inventory_reason": "Published through an explicit publication.json document entry.", "missing_fields": [], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "First-wave stub, published.", "source_path": "docs/architecture/policy-nexus_v0.1.md", "source_repo": "policy-nexus", "successor": "" @@ -2886,8 +2867,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "k3s API exposure binds the fleet.", "source_path": "docs/adr/ADR-005-k3s-api-tunnel-only.md", "source_repo": "railiance-infra", "successor": "" @@ -3185,10 +3166,10 @@ "file_present": true, "frontmatter": { "id": "railiance-architecture", - "last_reviewed": "2026-08-18", + "last_reviewed": "2026-08-19", "owner": "railiance-master", "review_interval": "6m", - "revision": "draft-1", + "revision": "draft-2", "status": "proposed", "title": "Railiance architecture", "updated": "", @@ -3199,8 +3180,8 @@ "inventory_reason": "Published through an explicit publication.json document entry.", "missing_fields": [], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "First-wave stub, published.", "source_path": "docs/architecture/railiance_v0.1.md", "source_repo": "railiance-master", "successor": "" @@ -3227,7 +3208,7 @@ "conflict_kinds": [], "file_present": true, "frontmatter": { - "id": "", + "id": "RPLAT-ADR-0001", "last_reviewed": "2026-08-17", "owner": "railiance-platform", "review_interval": "12m", @@ -3238,11 +3219,9 @@ "version": "" }, "id_collisions": [], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "id" - ], + "inventory_disposition": "published", + "inventory_reason": "Published through an explicit publication.json document entry.", + "missing_fields": [], "notes": "", "proposed_disposition": "publish", "review_notes": "Binds other repos on S3. Needs a unique publication id in front-matter.", @@ -3270,7 +3249,7 @@ "conflict_kinds": [], "file_present": true, "frontmatter": { - "id": "", + "id": "RPLAT-ADR-0002", "last_reviewed": "2026-08-17", "owner": "railiance-platform", "review_interval": "6m", @@ -3281,11 +3260,9 @@ "version": "" }, "id_collisions": [], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "id" - ], + "inventory_disposition": "published", + "inventory_reason": "Published through an explicit publication.json document entry.", + "missing_fields": [], "notes": "", "proposed_disposition": "publish", "review_notes": "Proposed placement-policy ownership. Bindings are cross-repo. Needs a unique id.", @@ -3311,7 +3288,7 @@ "conflict_kinds": [], "file_present": true, "frontmatter": { - "id": "", + "id": "RPLAT-ADR-0003", "last_reviewed": "2026-08-17", "owner": "railiance-platform", "review_interval": "12m", @@ -3322,11 +3299,9 @@ "version": "" }, "id_collisions": [], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "id" - ], + "inventory_disposition": "published", + "inventory_reason": "Published through an explicit publication.json document entry.", + "missing_fields": [], "notes": "", "proposed_disposition": "publish", "review_notes": "Restates ADR-001 for this repo. Needs a unique publication id (front-matter has title but no id).", @@ -3357,8 +3332,8 @@ "id" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "local", + "review_notes": "Directory index, not a governing record.", "source_path": "docs/adr/README.md", "source_repo": "railiance-platform", "successor": "" @@ -3407,8 +3382,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Shared storage isolation binds consumers.", "source_path": "docs/adr/ADR-0001-consumer-boundary-and-tenant-isolation.md", "source_repo": "rapp-postgres", "successor": "" @@ -3455,8 +3430,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Retention/erasure on shared PG.", "source_path": "docs/adr/ADR-0002-data-retention-and-erasure.md", "source_repo": "rapp-postgres", "successor": "" @@ -3501,8 +3476,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "E3 RLS contract.", "source_path": "docs/adr/ADR-0003-e3-row-level-security-contract.md", "source_repo": "rapp-postgres", "successor": "" @@ -3546,8 +3521,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Cell ceiling binds placement.", "source_path": "docs/adr/ADR-0004-platform-pg-cell-ceiling.md", "source_repo": "rapp-postgres", "successor": "" @@ -3588,8 +3563,7 @@ }, "id_collisions": [ "coulomb-loop/docs/adr/ADR-001-workplan-prefix.md", - "kaizen-agentic/docs/adr/ADR-001-workplan-convention.md", - "the-custodian/canon/architecture/adr-001-workplans-as-repo-artefacts.md" + "kaizen-agentic/docs/adr/ADR-001-workplan-convention.md" ], "inventory_disposition": "metadata-pending", "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", @@ -3599,8 +3573,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "Front-matter id 'ADR-001' is shared; pick a repo-prefixed publication id before publish. Who rules: owning repo.", + "proposed_disposition": "publish", + "review_notes": "Shared harness, instances in consumers.", "source_path": "docs/adr/ADR-001-agent-harness-architecture.md", "source_repo": "rein-aharness", "successor": "" @@ -3612,10 +3586,10 @@ "file_present": true, "frontmatter": { "id": "state-hub-architecture", - "last_reviewed": "2026-08-18", + "last_reviewed": "2026-08-19", "owner": "state-hub", "review_interval": "6m", - "revision": "draft-1", + "revision": "draft-2", "status": "proposed", "title": "State Hub architecture", "updated": "", @@ -3626,8 +3600,8 @@ "inventory_reason": "Published through an explicit publication.json document entry.", "missing_fields": [], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "First-wave stub, published.", "source_path": "docs/architecture/state-hub_v0.1.md", "source_repo": "state-hub", "successor": "" @@ -3678,8 +3652,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "Front-matter id 'ADR-0001' is shared; pick a repo-prefixed publication id before publish. Who rules: owning repo.", + "proposed_disposition": "local", + "review_notes": "Product stack choice.", "source_path": "docs/adr/ADR-0001-stage0-library-stack.md", "source_repo": "target-revenue", "successor": "" @@ -3723,8 +3697,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "local", + "review_notes": "Product stack choice.", "source_path": "docs/adr/ADR-0002-hosted-trust-service-stack.md", "source_repo": "target-revenue", "successor": "" @@ -3753,28 +3727,20 @@ ], "file_present": true, "frontmatter": { - "id": "ADR-001", - "last_reviewed": "", - "owner": "", - "review_interval": "", - "revision": "", + "id": "CUST-ADR-001", + "last_reviewed": "2026-02-28", + "owner": "the-custodian", + "review_interval": "6m", + "revision": "accepted-1", "status": "accepted", "title": "Workplans and Work Items Are Repository Artefacts", "updated": "", "version": "" }, - "id_collisions": [ - "coulomb-loop/docs/adr/ADR-001-workplan-prefix.md", - "kaizen-agentic/docs/adr/ADR-001-workplan-convention.md", - "rein-aharness/docs/adr/ADR-001-agent-harness-architecture.md" - ], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "owner", - "revision|version", - "review" - ], + "id_collisions": [], + "inventory_disposition": "published", + "inventory_reason": "Published through an explicit publication.json document entry.", + "missing_fields": [], "notes": "", "proposed_disposition": "publish", "review_notes": "Estate rule: workplans originate as repo files. Needs a unique publication id (e.g. CUST-ADR-001) before publish.", @@ -3804,27 +3770,20 @@ ], "file_present": true, "frontmatter": { - "id": "ADR-002", - "last_reviewed": "", - "owner": "", - "review_interval": "", - "revision": "", + "id": "CUST-ADR-002", + "last_reviewed": "2026-03-12", + "owner": "the-custodian", + "review_interval": "6m", + "revision": "accepted-1", "status": "accepted", "title": "Custodian Agent Runtime \u2014 v0.1 Bootstrap Design", "updated": "", "version": "" }, - "id_collisions": [ - "coulomb-loop/docs/adr/ADR-002-customer-supplier-boundary.md", - "kaizen-agentic/docs/adr/ADR-002-project-memory-convention.md" - ], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "owner", - "revision|version", - "review" - ], + "id_collisions": [], + "inventory_disposition": "published", + "inventory_reason": "Published through an explicit publication.json document entry.", + "missing_fields": [], "notes": "", "proposed_disposition": "publish", "review_notes": "Estate ADR. Prefix the publication id before publish.", @@ -3852,27 +3811,20 @@ ], "file_present": true, "frontmatter": { - "id": "ADR-003", - "last_reviewed": "", - "owner": "", - "review_interval": "", - "revision": "", + "id": "CUST-ADR-003", + "last_reviewed": "2026-03-20", + "owner": "the-custodian", + "review_interval": "6m", + "revision": "accepted-1", "status": "accepted", "title": "Materialized Derived State with Fingerprint Invalidation for Repo-Sourced Data", "updated": "", "version": "" }, - "id_collisions": [ - "coulomb-loop/docs/adr/ADR-003-cadence-ramp-policy.md", - "kaizen-agentic/docs/adr/ADR-003-protocols-artifact-convention.md" - ], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "owner", - "revision|version", - "review" - ], + "id_collisions": [], + "inventory_disposition": "published", + "inventory_reason": "Published through an explicit publication.json document entry.", + "missing_fields": [], "notes": "", "proposed_disposition": "publish", "review_notes": "Estate ADR: hub is a derived read-model. Prefix the publication id before publish.", @@ -3899,27 +3851,20 @@ ], "file_present": true, "frontmatter": { - "id": "ADR-004", - "last_reviewed": "", - "owner": "", - "review_interval": "", - "revision": "", + "id": "CUST-ADR-004", + "last_reviewed": "2026-03-26", + "owner": "the-custodian", + "review_interval": "6m", + "revision": "accepted-1", "status": "accepted", "title": "Connectivity-First Network Posture for Custodian Infrastructure", "updated": "", "version": "" }, - "id_collisions": [ - "coulomb-loop/docs/adr/ADR-004-repo-rotation-on-diminishing-returns.md", - "kaizen-agentic/docs/adr/ADR-004-project-metrics-convention.md" - ], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "owner", - "revision|version", - "review" - ], + "id_collisions": [], + "inventory_disposition": "published", + "inventory_reason": "Published through an explicit publication.json document entry.", + "missing_fields": [], "notes": "", "proposed_disposition": "publish", "review_notes": "Estate ADR. Prefix the publication id before publish.", @@ -3941,26 +3886,20 @@ ], "file_present": true, "frontmatter": { - "id": "ADR-005", - "last_reviewed": "", - "owner": "", - "review_interval": "", - "revision": "", + "id": "CUST-ADR-005", + "last_reviewed": "2026-06-22", + "owner": "the-custodian", + "review_interval": "6m", + "revision": "accepted-1", "status": "accepted", "title": "Cross-Repo Workplans Live in Dedicated Project Repos", "updated": "", "version": "" }, - "id_collisions": [ - "kaizen-agentic/docs/adr/ADR-005-scheduled-agent-execution.md" - ], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "owner", - "revision|version", - "review" - ], + "id_collisions": [], + "inventory_disposition": "published", + "inventory_reason": "Published through an explicit publication.json document entry.", + "missing_fields": [], "notes": "", "proposed_disposition": "publish", "review_notes": "Estate ADR. Prefix the publication id before publish.", @@ -3978,24 +3917,20 @@ "conflict_kinds": [], "file_present": true, "frontmatter": { - "id": "ADR-006", - "last_reviewed": "", - "owner": "", - "review_interval": "", - "revision": "", + "id": "CUST-ADR-006", + "last_reviewed": "2026-08-17", + "owner": "the-custodian", + "review_interval": "6m", + "revision": "accepted-1", "status": "accepted", "title": "Canon Federation and Concept Ownership Across InfoTech and Commerce", "updated": "", "version": "" }, "id_collisions": [], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "owner", - "revision|version", - "review" - ], + "inventory_disposition": "published", + "inventory_reason": "Published through an explicit publication.json document entry.", + "missing_fields": [], "notes": "", "proposed_disposition": "publish", "review_notes": "Estate ADR. Id ADR-006 is unique in front-matter today; still prefix for consistency.", @@ -4013,24 +3948,20 @@ "conflict_kinds": [], "file_present": true, "frontmatter": { - "id": "ADR-007", - "last_reviewed": "", - "owner": "", - "review_interval": "", - "revision": "", + "id": "CUST-ADR-007", + "last_reviewed": "2026-08-17", + "owner": "the-custodian", + "review_interval": "6m", + "revision": "accepted-1", "status": "accepted", "title": "Workplan Identity Uniqueness, Single Registrar, and Repo Worker Topology", "updated": "", "version": "" }, "id_collisions": [], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "owner", - "revision|version", - "review" - ], + "inventory_disposition": "published", + "inventory_reason": "Published through an explicit publication.json document entry.", + "missing_fields": [], "notes": "", "proposed_disposition": "publish", "review_notes": "Estate ADR. Prefix the publication id for consistency.", @@ -4082,24 +4013,20 @@ "conflict_kinds": [], "file_present": true, "frontmatter": { - "id": "ADR-010", - "last_reviewed": "", - "owner": "", - "review_interval": "", - "revision": "", + "id": "CUST-ADR-010", + "last_reviewed": "2026-08-17", + "owner": "the-custodian", + "review_interval": "6m", + "revision": "draft-1", "status": "proposed", "title": "Hub Authority, Local Cache, and the Two Kinds of Hub Data", "updated": "", "version": "" }, "id_collisions": [], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "owner", - "revision|version", - "review" - ], + "inventory_disposition": "published", + "inventory_reason": "Published through an explicit publication.json document entry.", + "missing_fields": [], "notes": "", "proposed_disposition": "publish", "review_notes": "Proposed estate ADR. Publish as proposed once prefixed and review metadata is added.", @@ -4115,10 +4042,10 @@ "conflict_kinds": [], "file_present": true, "frontmatter": { - "id": "ADR-011", - "last_reviewed": "", - "owner": "", - "review_interval": "", + "id": "CUST-ADR-011", + "last_reviewed": "2026-08-17", + "owner": "the-custodian", + "review_interval": "6m", "revision": "draft-2", "status": "proposed", "title": "Federated Namespaces: Four Planes, Declared Posture, and the Limits of Reconciliation", @@ -4126,12 +4053,9 @@ "version": "" }, "id_collisions": [], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "owner", - "review" - ], + "inventory_disposition": "published", + "inventory_reason": "Published through an explicit publication.json document entry.", + "missing_fields": [], "notes": "", "proposed_disposition": "publish", "review_notes": "Proposed estate ADR. Publish as proposed once prefixed and review metadata is added.", @@ -4146,10 +4070,10 @@ "file_present": true, "frontmatter": { "id": "coulomb-estate-architecture", - "last_reviewed": "2026-08-18", + "last_reviewed": "2026-08-19", "owner": "the-custodian", "review_interval": "6m", - "revision": "draft-1", + "revision": "draft-2", "status": "proposed", "title": "Coulomb estate architecture", "updated": "", @@ -4160,104 +4084,12 @@ "inventory_reason": "Published through an explicit publication.json document entry.", "missing_fields": [], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "First-wave stub, published.", "source_path": "canon/architecture/coulomb-estate_v0.1.md", "source_repo": "the-custodian", "successor": "" }, - { - "bare_adr": "", - "bare_adr_collisions": [], - "conflict_kinds": [], - "file_present": true, - "frontmatter": { - "id": "CUST-BSP-2026-000001", - "last_reviewed": "", - "owner": "", - "review_interval": "", - "revision": "", - "status": "draft", - "title": "Bootstrap Protocol v0.1", - "updated": "2026-07-08", - "version": "" - }, - "id_collisions": [], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "owner", - "revision|version", - "review" - ], - "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", - "source_path": "canon/constitution/bootstrap-protocol_v0.1.md", - "source_repo": "the-custodian", - "successor": "" - }, - { - "bare_adr": "", - "bare_adr_collisions": [], - "conflict_kinds": [], - "file_present": true, - "frontmatter": { - "id": "CUST-CONST-2026-000001", - "last_reviewed": "", - "owner": "", - "review_interval": "", - "revision": "", - "status": "active", - "title": "Custodian Constitution v0.1", - "updated": "2026-02-24", - "version": "" - }, - "id_collisions": [], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "owner", - "revision|version", - "review" - ], - "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", - "source_path": "canon/constitution/custodian_constitution_v0.1.md", - "source_repo": "the-custodian", - "successor": "" - }, - { - "bare_adr": "", - "bare_adr_collisions": [], - "conflict_kinds": [], - "file_present": true, - "frontmatter": { - "id": "canon-autonomy-lanes", - "last_reviewed": "", - "owner": "", - "review_interval": "", - "revision": "", - "status": "active", - "title": "Autonomy Lanes (Fleet) v0.1", - "updated": "2026-07-20", - "version": "0.1" - }, - "id_collisions": [], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "owner", - "review" - ], - "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", - "source_path": "canon/standards/autonomy-lanes_v0.1.md", - "source_repo": "the-custodian", - "successor": "" - }, { "bare_adr": "", "bare_adr_collisions": [], @@ -4269,46 +4101,18 @@ "owner": "", "review_interval": "", "revision": "", - "status": "accepted", - "title": "Business-App Service Contract", + "status": "", + "title": "", "updated": "", - "version": "v0.1" + "version": "" }, "id_collisions": [], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "inventory_disposition": "unsupported-format", + "inventory_reason": "Inventoried governing source is not Markdown and has no renderer yet.", "missing_fields": [ "id", - "owner", - "review" - ], - "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", - "source_path": "canon/standards/business-app-service-contract_v0.1.md", - "source_repo": "the-custodian", - "successor": "" - }, - { - "bare_adr": "", - "bare_adr_collisions": [], - "conflict_kinds": [], - "file_present": true, - "frontmatter": { - "id": "br-YYYY-MM-DD--org--repo--slug", - "last_reviewed": "", - "owner": "", - "review_interval": "", - "revision": "", - "status": "draft", - "title": "Short description of the bug", - "updated": "YYYY-MM-DD", - "version": "" - }, - "id_collisions": [], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ + "title", + "status", "owner", "revision|version", "review" @@ -4316,191 +4120,7 @@ "notes": "", "proposed_disposition": "unreviewed", "review_notes": "", - "source_path": "canon/standards/contrib-templates/br-template.md", - "source_repo": "the-custodian", - "successor": "" - }, - { - "bare_adr": "", - "bare_adr_collisions": [], - "conflict_kinds": [], - "file_present": true, - "frontmatter": { - "id": "EP-DOMAIN-NNN", - "last_reviewed": "", - "owner": "", - "review_interval": "", - "revision": "", - "status": "draft", - "title": "Short description of the extension point", - "updated": "YYYY-MM-DD", - "version": "" - }, - "id_collisions": [], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "owner", - "revision|version", - "review" - ], - "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", - "source_path": "canon/standards/contrib-templates/ep-template.md", - "source_repo": "the-custodian", - "successor": "" - }, - { - "bare_adr": "", - "bare_adr_collisions": [], - "conflict_kinds": [], - "file_present": true, - "frontmatter": { - "id": "fr-YYYY-MM-DD--org--repo--slug", - "last_reviewed": "", - "owner": "", - "review_interval": "", - "revision": "", - "status": "draft", - "title": "Short description of the requested feature", - "updated": "YYYY-MM-DD", - "version": "" - }, - "id_collisions": [], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "owner", - "revision|version", - "review" - ], - "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", - "source_path": "canon/standards/contrib-templates/fr-template.md", - "source_repo": "the-custodian", - "successor": "" - }, - { - "bare_adr": "", - "bare_adr_collisions": [], - "conflict_kinds": [], - "file_present": true, - "frontmatter": { - "id": "upr-YYYY-MM-DD--org--repo--slug", - "last_reviewed": "", - "owner": "", - "review_interval": "", - "revision": "", - "status": "draft", - "title": "Short description of the upstream PR", - "updated": "YYYY-MM-DD", - "version": "" - }, - "id_collisions": [], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "owner", - "revision|version", - "review" - ], - "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", - "source_path": "canon/standards/contrib-templates/upr-template.md", - "source_repo": "the-custodian", - "successor": "" - }, - { - "bare_adr": "", - "bare_adr_collisions": [], - "conflict_kinds": [], - "file_present": true, - "frontmatter": { - "id": "canon-contrib-convention", - "last_reviewed": "", - "owner": "", - "review_interval": "", - "revision": "", - "status": "active", - "title": "Contribution Convention v0.1", - "updated": "", - "version": "0.1" - }, - "id_collisions": [], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "owner", - "review" - ], - "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", - "source_path": "canon/standards/contribution-convention_v0.1.md", - "source_repo": "the-custodian", - "successor": "" - }, - { - "bare_adr": "", - "bare_adr_collisions": [], - "conflict_kinds": [], - "file_present": true, - "frontmatter": { - "id": "canon-coulombcore-production-freeze", - "last_reviewed": "", - "owner": "", - "review_interval": "", - "revision": "", - "status": "active", - "title": "CoulombCore Production Freeze v0.1", - "updated": "", - "version": "0.1" - }, - "id_collisions": [], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "owner", - "review" - ], - "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", - "source_path": "canon/standards/coulombcore-production-freeze_v0.1.md", - "source_repo": "the-custodian", - "successor": "" - }, - { - "bare_adr": "", - "bare_adr_collisions": [], - "conflict_kinds": [], - "file_present": true, - "frontmatter": { - "id": "", - "last_reviewed": "", - "owner": "", - "review_interval": "", - "revision": "", - "status": "Draft Standard", - "title": "Credential Management Standard", - "updated": "", - "version": "0.1" - }, - "id_collisions": [], - "inventory_disposition": "metadata-pending", - "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", - "missing_fields": [ - "id", - "owner", - "review" - ], - "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", - "source_path": "canon/standards/credential-management_v0.1.md", + "source_path": "canon/architecture/infospace/.gitignore", "source_repo": "the-custodian", "successor": "" }, @@ -4534,6 +4154,582 @@ "notes": "", "proposed_disposition": "unreviewed", "review_notes": "", + "source_path": "canon/architecture/infospace/discipline/arc42.md", + "source_repo": "the-custodian", + "successor": "" + }, + { + "bare_adr": "", + "bare_adr_collisions": [], + "conflict_kinds": [], + "file_present": true, + "frontmatter": { + "id": "", + "last_reviewed": "", + "owner": "", + "review_interval": "", + "revision": "", + "status": "", + "title": "", + "updated": "", + "version": "" + }, + "id_collisions": [], + "inventory_disposition": "metadata-pending", + "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "missing_fields": [ + "id", + "title", + "status", + "owner", + "revision|version", + "review" + ], + "notes": "", + "proposed_disposition": "unreviewed", + "review_notes": "", + "source_path": "canon/architecture/infospace/entities/coulomb-estate.md", + "source_repo": "the-custodian", + "successor": "" + }, + { + "bare_adr": "", + "bare_adr_collisions": [], + "conflict_kinds": [], + "file_present": true, + "frontmatter": { + "id": "", + "last_reviewed": "", + "owner": "", + "review_interval": "", + "revision": "", + "status": "", + "title": "", + "updated": "", + "version": "" + }, + "id_collisions": [], + "inventory_disposition": "metadata-pending", + "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "missing_fields": [ + "id", + "title", + "status", + "owner", + "revision|version", + "review" + ], + "notes": "", + "proposed_disposition": "unreviewed", + "review_notes": "", + "source_path": "canon/architecture/infospace/entities/net-kingdom.md", + "source_repo": "the-custodian", + "successor": "" + }, + { + "bare_adr": "", + "bare_adr_collisions": [], + "conflict_kinds": [], + "file_present": true, + "frontmatter": { + "id": "", + "last_reviewed": "", + "owner": "", + "review_interval": "", + "revision": "", + "status": "", + "title": "", + "updated": "", + "version": "" + }, + "id_collisions": [], + "inventory_disposition": "metadata-pending", + "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "missing_fields": [ + "id", + "title", + "status", + "owner", + "revision|version", + "review" + ], + "notes": "", + "proposed_disposition": "unreviewed", + "review_notes": "", + "source_path": "canon/architecture/infospace/entities/policy-nexus.md", + "source_repo": "the-custodian", + "successor": "" + }, + { + "bare_adr": "", + "bare_adr_collisions": [], + "conflict_kinds": [], + "file_present": true, + "frontmatter": { + "id": "", + "last_reviewed": "", + "owner": "", + "review_interval": "", + "revision": "", + "status": "", + "title": "", + "updated": "", + "version": "" + }, + "id_collisions": [], + "inventory_disposition": "metadata-pending", + "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "missing_fields": [ + "id", + "title", + "status", + "owner", + "revision|version", + "review" + ], + "notes": "", + "proposed_disposition": "unreviewed", + "review_notes": "", + "source_path": "canon/architecture/infospace/entities/railiance.md", + "source_repo": "the-custodian", + "successor": "" + }, + { + "bare_adr": "", + "bare_adr_collisions": [], + "conflict_kinds": [], + "file_present": true, + "frontmatter": { + "id": "", + "last_reviewed": "", + "owner": "", + "review_interval": "", + "revision": "", + "status": "", + "title": "", + "updated": "", + "version": "" + }, + "id_collisions": [], + "inventory_disposition": "metadata-pending", + "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "missing_fields": [ + "id", + "title", + "status", + "owner", + "revision|version", + "review" + ], + "notes": "", + "proposed_disposition": "unreviewed", + "review_notes": "", + "source_path": "canon/architecture/infospace/entities/state-hub.md", + "source_repo": "the-custodian", + "successor": "" + }, + { + "bare_adr": "", + "bare_adr_collisions": [], + "conflict_kinds": [], + "file_present": true, + "frontmatter": { + "id": "", + "last_reviewed": "", + "owner": "", + "review_interval": "", + "revision": "", + "status": "", + "title": "", + "updated": "", + "version": "" + }, + "id_collisions": [], + "inventory_disposition": "unsupported-format", + "inventory_reason": "Inventoried governing source is not Markdown and has no renderer yet.", + "missing_fields": [ + "id", + "title", + "status", + "owner", + "revision|version", + "review" + ], + "notes": "", + "proposed_disposition": "unreviewed", + "review_notes": "", + "source_path": "canon/architecture/infospace/infospace.yaml", + "source_repo": "the-custodian", + "successor": "" + }, + { + "bare_adr": "", + "bare_adr_collisions": [], + "conflict_kinds": [], + "file_present": true, + "frontmatter": { + "id": "CUST-BSP-2026-000001", + "last_reviewed": "", + "owner": "", + "review_interval": "", + "revision": "", + "status": "draft", + "title": "Bootstrap Protocol v0.1", + "updated": "2026-07-08", + "version": "" + }, + "id_collisions": [], + "inventory_disposition": "metadata-pending", + "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "missing_fields": [ + "owner", + "revision|version", + "review" + ], + "notes": "", + "proposed_disposition": "publish", + "review_notes": "Bootstrap protocol.", + "source_path": "canon/constitution/bootstrap-protocol_v0.1.md", + "source_repo": "the-custodian", + "successor": "" + }, + { + "bare_adr": "", + "bare_adr_collisions": [], + "conflict_kinds": [], + "file_present": true, + "frontmatter": { + "id": "CUST-CONST-2026-000001", + "last_reviewed": "", + "owner": "", + "review_interval": "", + "revision": "", + "status": "active", + "title": "Custodian Constitution v0.1", + "updated": "2026-02-24", + "version": "" + }, + "id_collisions": [], + "inventory_disposition": "metadata-pending", + "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "missing_fields": [ + "owner", + "revision|version", + "review" + ], + "notes": "", + "proposed_disposition": "publish", + "review_notes": "Estate constitution.", + "source_path": "canon/constitution/custodian_constitution_v0.1.md", + "source_repo": "the-custodian", + "successor": "" + }, + { + "bare_adr": "", + "bare_adr_collisions": [], + "conflict_kinds": [], + "file_present": true, + "frontmatter": { + "id": "canon-autonomy-lanes", + "last_reviewed": "", + "owner": "", + "review_interval": "", + "revision": "", + "status": "active", + "title": "Autonomy Lanes (Fleet) v0.1", + "updated": "2026-07-20", + "version": "0.1" + }, + "id_collisions": [], + "inventory_disposition": "metadata-pending", + "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "missing_fields": [ + "owner", + "review" + ], + "notes": "", + "proposed_disposition": "publish", + "review_notes": "Autonomy lanes.", + "source_path": "canon/standards/autonomy-lanes_v0.1.md", + "source_repo": "the-custodian", + "successor": "" + }, + { + "bare_adr": "", + "bare_adr_collisions": [], + "conflict_kinds": [], + "file_present": true, + "frontmatter": { + "id": "", + "last_reviewed": "", + "owner": "", + "review_interval": "", + "revision": "", + "status": "accepted", + "title": "Business-App Service Contract", + "updated": "", + "version": "v0.1" + }, + "id_collisions": [], + "inventory_disposition": "metadata-pending", + "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "missing_fields": [ + "id", + "owner", + "review" + ], + "notes": "", + "proposed_disposition": "local", + "review_notes": "App contract; owner should confirm governing vs local.", + "source_path": "canon/standards/business-app-service-contract_v0.1.md", + "source_repo": "the-custodian", + "successor": "" + }, + { + "bare_adr": "", + "bare_adr_collisions": [], + "conflict_kinds": [], + "file_present": true, + "frontmatter": { + "id": "br-YYYY-MM-DD--org--repo--slug", + "last_reviewed": "", + "owner": "", + "review_interval": "", + "revision": "", + "status": "draft", + "title": "Short description of the bug", + "updated": "YYYY-MM-DD", + "version": "" + }, + "id_collisions": [], + "inventory_disposition": "metadata-pending", + "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "missing_fields": [ + "owner", + "revision|version", + "review" + ], + "notes": "", + "proposed_disposition": "local", + "review_notes": "Template, not governing.", + "source_path": "canon/standards/contrib-templates/br-template.md", + "source_repo": "the-custodian", + "successor": "" + }, + { + "bare_adr": "", + "bare_adr_collisions": [], + "conflict_kinds": [], + "file_present": true, + "frontmatter": { + "id": "EP-DOMAIN-NNN", + "last_reviewed": "", + "owner": "", + "review_interval": "", + "revision": "", + "status": "draft", + "title": "Short description of the extension point", + "updated": "YYYY-MM-DD", + "version": "" + }, + "id_collisions": [], + "inventory_disposition": "metadata-pending", + "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "missing_fields": [ + "owner", + "revision|version", + "review" + ], + "notes": "", + "proposed_disposition": "local", + "review_notes": "Template, not governing.", + "source_path": "canon/standards/contrib-templates/ep-template.md", + "source_repo": "the-custodian", + "successor": "" + }, + { + "bare_adr": "", + "bare_adr_collisions": [], + "conflict_kinds": [], + "file_present": true, + "frontmatter": { + "id": "fr-YYYY-MM-DD--org--repo--slug", + "last_reviewed": "", + "owner": "", + "review_interval": "", + "revision": "", + "status": "draft", + "title": "Short description of the requested feature", + "updated": "YYYY-MM-DD", + "version": "" + }, + "id_collisions": [], + "inventory_disposition": "metadata-pending", + "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "missing_fields": [ + "owner", + "revision|version", + "review" + ], + "notes": "", + "proposed_disposition": "local", + "review_notes": "Template, not governing.", + "source_path": "canon/standards/contrib-templates/fr-template.md", + "source_repo": "the-custodian", + "successor": "" + }, + { + "bare_adr": "", + "bare_adr_collisions": [], + "conflict_kinds": [], + "file_present": true, + "frontmatter": { + "id": "upr-YYYY-MM-DD--org--repo--slug", + "last_reviewed": "", + "owner": "", + "review_interval": "", + "revision": "", + "status": "draft", + "title": "Short description of the upstream PR", + "updated": "YYYY-MM-DD", + "version": "" + }, + "id_collisions": [], + "inventory_disposition": "metadata-pending", + "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "missing_fields": [ + "owner", + "revision|version", + "review" + ], + "notes": "", + "proposed_disposition": "local", + "review_notes": "Template, not governing.", + "source_path": "canon/standards/contrib-templates/upr-template.md", + "source_repo": "the-custodian", + "successor": "" + }, + { + "bare_adr": "", + "bare_adr_collisions": [], + "conflict_kinds": [], + "file_present": true, + "frontmatter": { + "id": "canon-contrib-convention", + "last_reviewed": "", + "owner": "", + "review_interval": "", + "revision": "", + "status": "active", + "title": "Contribution Convention v0.1", + "updated": "", + "version": "0.1" + }, + "id_collisions": [], + "inventory_disposition": "metadata-pending", + "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "missing_fields": [ + "owner", + "review" + ], + "notes": "", + "proposed_disposition": "publish", + "review_notes": "Contribution convention.", + "source_path": "canon/standards/contribution-convention_v0.1.md", + "source_repo": "the-custodian", + "successor": "" + }, + { + "bare_adr": "", + "bare_adr_collisions": [], + "conflict_kinds": [], + "file_present": true, + "frontmatter": { + "id": "canon-coulombcore-production-freeze", + "last_reviewed": "", + "owner": "", + "review_interval": "", + "revision": "", + "status": "active", + "title": "CoulombCore Production Freeze v0.1", + "updated": "", + "version": "0.1" + }, + "id_collisions": [], + "inventory_disposition": "metadata-pending", + "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "missing_fields": [ + "owner", + "review" + ], + "notes": "", + "proposed_disposition": "local", + "review_notes": "Time-boxed freeze, not standing architecture.", + "source_path": "canon/standards/coulombcore-production-freeze_v0.1.md", + "source_repo": "the-custodian", + "successor": "" + }, + { + "bare_adr": "", + "bare_adr_collisions": [], + "conflict_kinds": [], + "file_present": true, + "frontmatter": { + "id": "", + "last_reviewed": "", + "owner": "", + "review_interval": "", + "revision": "", + "status": "Draft Standard", + "title": "Credential Management Standard", + "updated": "", + "version": "0.1" + }, + "id_collisions": [], + "inventory_disposition": "metadata-pending", + "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "missing_fields": [ + "id", + "owner", + "review" + ], + "notes": "", + "proposed_disposition": "local", + "review_notes": "Superseded in spirit by net-kingdom credential standard; leave local until owner marks successor.", + "source_path": "canon/standards/credential-management_v0.1.md", + "source_repo": "the-custodian", + "successor": "" + }, + { + "bare_adr": "", + "bare_adr_collisions": [], + "conflict_kinds": [], + "file_present": true, + "frontmatter": { + "id": "", + "last_reviewed": "", + "owner": "", + "review_interval": "", + "revision": "", + "status": "", + "title": "", + "updated": "", + "version": "" + }, + "id_collisions": [], + "inventory_disposition": "metadata-pending", + "inventory_reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "missing_fields": [ + "id", + "title", + "status", + "owner", + "revision|version", + "review" + ], + "notes": "", + "proposed_disposition": "local", + "review_notes": "Draft; not yet governing.", "source_path": "canon/standards/federated-organization-standard_v1.0.md", "source_repo": "the-custodian", "successor": "" @@ -4598,8 +4794,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "local", + "review_notes": "Schema companion to draft OAS.", "source_path": "canon/standards/orthogonal-architecture-schema_v1.0.1.md", "source_repo": "the-custodian", "successor": "" @@ -4632,8 +4828,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "local", + "review_notes": "Draft OAS.", "source_path": "canon/standards/orthogonal-architecture_v1.0.md", "source_repo": "the-custodian", "successor": "" @@ -4666,8 +4862,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "local", + "review_notes": "Schema companion.", "source_path": "canon/standards/privileged-execution-control-schema-cicd_v0.2.1.md", "source_repo": "the-custodian", "successor": "" @@ -4700,8 +4896,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "local", + "review_notes": "Schema companion.", "source_path": "canon/standards/privileged-execution-control-schema-kubernetes-rbac_v0.2.1.md", "source_repo": "the-custodian", "successor": "" @@ -4734,8 +4930,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "local", + "review_notes": "Schema companion.", "source_path": "canon/standards/privileged-execution-control-schema-os-sudo_v0.2.1.md", "source_repo": "the-custodian", "successor": "" @@ -4768,8 +4964,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "local", + "review_notes": "Schema companion.", "source_path": "canon/standards/privileged-execution-control-schema_v0.2.1.md", "source_repo": "the-custodian", "successor": "" @@ -4832,8 +5028,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "prj- flavor.", "source_path": "canon/standards/project-repository-flavor_v0.1.md", "source_repo": "the-custodian", "successor": "" @@ -4862,8 +5058,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Repo classification.", "source_path": "canon/standards/repo-classification-standard_v1.0.md", "source_repo": "the-custodian", "successor": "" @@ -4960,8 +5156,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "SBOM convention.", "source_path": "canon/standards/sbom-convention_v0.1.md", "source_repo": "the-custodian", "successor": "" @@ -5160,8 +5356,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Work-record type registry.", "source_path": "canon/standards/work-record-types_v0.1.md", "source_repo": "the-custodian", "successor": "" @@ -5190,8 +5386,8 @@ "review" ], "notes": "", - "proposed_disposition": "unreviewed", - "review_notes": "", + "proposed_disposition": "publish", + "review_notes": "Fleet workplan terminology.", "source_path": "canon/standards/workplan-terminology-fleet_v0.1.md", "source_repo": "the-custodian", "successor": "" diff --git a/docs/adr-review/rulings.json b/docs/adr-review/rulings.json index 2d9b82d..3f29aca 100644 --- a/docs/adr-review/rulings.json +++ b/docs/adr-review/rulings.json @@ -34,7 +34,7 @@ 6 ], "successor": "net-kingdom/canon/standards/iam-profile_v0.3.md", - "review_notes": "v0.3 says it supersedes v0.2, but v0.2 is still status accepted and shares id netkingdom-iam-profile. Who rules: net-kingdom (status + unique id)." + "review_notes": "Status set to superseded; unique id netkingdom-iam-profile-v0.2." }, { "source_repo": "net-kingdom", @@ -45,7 +45,7 @@ 6 ], "successor": "", - "review_notes": "Current IAM profile. Cannot publish until id is unique (e.g. netkingdom-iam-profile-v0.3). Who rules: net-kingdom." + "review_notes": "Id now netkingdom-iam-profile-v0.3; ready to publish." }, { "source_repo": "railiance-hosts", @@ -304,6 +304,694 @@ "conflict_kinds": [], "successor": "", "review_notes": "Owner-ready; harvest request 2026-08-18." + }, + { + "source_repo": "net-kingdom", + "source_path": "canon/standards/tenancy-posture_v0.1.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Already published." + }, + { + "source_repo": "net-kingdom", + "source_path": "docs/architecture/net-kingdom_v0.1.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "First-wave stub, published." + }, + { + "source_repo": "policy-nexus", + "source_path": "docs/architecture/policy-nexus_v0.1.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "First-wave stub, published." + }, + { + "source_repo": "railiance-master", + "source_path": "docs/architecture/railiance_v0.1.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "First-wave stub, published." + }, + { + "source_repo": "state-hub", + "source_path": "docs/architecture/state-hub_v0.1.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "First-wave stub, published." + }, + { + "source_repo": "the-custodian", + "source_path": "canon/architecture/coulomb-estate_v0.1.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "First-wave stub, published." + }, + { + "source_repo": "artifact-store", + "source_path": "docs/adr/README.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Directory index, not a governing record." + }, + { + "source_repo": "ops-warden", + "source_path": "docs/adr/README.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Directory index, not a governing record." + }, + { + "source_repo": "railiance-platform", + "source_path": "docs/adr/README.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Directory index, not a governing record." + }, + { + "source_repo": "key-cape", + "source_path": "docs/adr/ADR-0001-choose-go-for-keycape.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Language choice; audience is this repo." + }, + { + "source_repo": "binect-js", + "source_path": "docs/adr/001-no-listall-method.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Client API shape; no cross-repo bind." + }, + { + "source_repo": "markitect-main", + "source_path": "docs/adr/ADR-001-client-side-debug-storage.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Implementation storage for debug UI." + }, + { + "source_repo": "markitect-main", + "source_path": "docs/adr/ADR-002-robustness-principle-for-production-use.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Product robustness note for Markitect." + }, + { + "source_repo": "evidence-binder", + "source_path": "docs/adr/ADR-0001-reference-ui-surface.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Binder-owned UI surface." + }, + { + "source_repo": "target-revenue", + "source_path": "docs/adr/ADR-0001-stage0-library-stack.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Product stack choice." + }, + { + "source_repo": "target-revenue", + "source_path": "docs/adr/ADR-0002-hosted-trust-service-stack.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Product stack choice." + }, + { + "source_repo": "artifact-store", + "source_path": "docs/adr/0005-v1-tech-stack.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "V1 stack preference, not a cross-repo contract." + }, + { + "source_repo": "glas-harness", + "source_path": "docs/adr/ADR-002-credential-brokering-and-composable-reins.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Partly open; not current governing." + }, + { + "source_repo": "glas-harness", + "source_path": "docs/adr/ADR-004-composable-reins-stay-deferred.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Explicitly deferred." + }, + { + "source_repo": "the-custodian", + "source_path": "canon/standards/contrib-templates/br-template.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Template, not governing." + }, + { + "source_repo": "the-custodian", + "source_path": "canon/standards/contrib-templates/ep-template.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Template, not governing." + }, + { + "source_repo": "the-custodian", + "source_path": "canon/standards/contrib-templates/fr-template.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Template, not governing." + }, + { + "source_repo": "the-custodian", + "source_path": "canon/standards/contrib-templates/upr-template.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Template, not governing." + }, + { + "source_repo": "flex-auth", + "source_path": "docs/adr/0001-implementation-language-and-skeleton.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Flex-auth implementers consume this." + }, + { + "source_repo": "flex-auth", + "source_path": "docs/adr/0002-rego-in-markdown-policy-format.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Policy format others write." + }, + { + "source_repo": "flex-auth", + "source_path": "docs/adr/0003-topaz-aligned-mvp.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Alignment contract for the evaluator." + }, + { + "source_repo": "flex-auth", + "source_path": "docs/adr/0004-inbound-caller-authentication.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Caller identity binds every check client." + }, + { + "source_repo": "rapp-postgres", + "source_path": "docs/adr/ADR-0001-consumer-boundary-and-tenant-isolation.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Shared storage isolation binds consumers." + }, + { + "source_repo": "rapp-postgres", + "source_path": "docs/adr/ADR-0002-data-retention-and-erasure.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Retention/erasure on shared PG." + }, + { + "source_repo": "rapp-postgres", + "source_path": "docs/adr/ADR-0003-e3-row-level-security-contract.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "E3 RLS contract." + }, + { + "source_repo": "rapp-postgres", + "source_path": "docs/adr/ADR-0004-platform-pg-cell-ceiling.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Cell ceiling binds placement." + }, + { + "source_repo": "artifact-store", + "source_path": "docs/adr/0001-content-addressed-storage.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Storage address contract." + }, + { + "source_repo": "artifact-store", + "source_path": "docs/adr/0002-event-log-source-of-truth.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Event-log SoR." + }, + { + "source_repo": "artifact-store", + "source_path": "docs/adr/0003-manifest-canonical-cbor.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Manifest canonicalisation." + }, + { + "source_repo": "artifact-store", + "source_path": "docs/adr/0004-control-plane-data-plane-contract.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Control/data plane split." + }, + { + "source_repo": "artifact-store", + "source_path": "docs/adr/0006-oci-compatibility-reachable.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "OCI reachability constraint." + }, + { + "source_repo": "net-kingdom", + "source_path": "canon/standards/credential-management_v0.2.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Credential standard for implementers." + }, + { + "source_repo": "net-kingdom", + "source_path": "canon/standards/playbook-capability-contract_v0.1.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Playbook contract." + }, + { + "source_repo": "net-kingdom", + "source_path": "canon/standards/tenant-engine-boundary-contract_v0.1.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Tenant-engine boundary." + }, + { + "source_repo": "net-kingdom", + "source_path": "canon/standards/user-engine-boundary-contract_v0.1.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "User-engine boundary." + }, + { + "source_repo": "net-kingdom", + "source_path": "docs/adr/ADR-0006-recursive-multi-tenant-identity-authorization.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Identity architecture others implement." + }, + { + "source_repo": "net-kingdom", + "source_path": "docs/adr/ADR-0007-security-orchestration-boundary.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Orchestration boundary." + }, + { + "source_repo": "net-kingdom", + "source_path": "docs/adr/ADR-0008-object-storage-sts-credential-vending.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "STS vending boundary." + }, + { + "source_repo": "net-kingdom", + "source_path": "docs/adr/ADR-0010-orchestration-vs-dependency-self-coherent-intent.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Orchestration vs dependency." + }, + { + "source_repo": "net-kingdom", + "source_path": "docs/adr/ADR-0011-iam-profile-ownership-and-version-governance.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "IAM profile ownership." + }, + { + "source_repo": "net-kingdom", + "source_path": "docs/adr/ADR-0012-playbook-capability-contract-ownership.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Playbook ownership." + }, + { + "source_repo": "net-kingdom", + "source_path": "docs/adr/ADR-0013-tenant-onboarding-grouping-taxonomy.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Onboarding taxonomy." + }, + { + "source_repo": "net-kingdom", + "source_path": "docs/adr/ADR-0014-tenant-capability-roles-and-tenant-engine-ownership.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Tenant capability roles." + }, + { + "source_repo": "net-kingdom", + "source_path": "docs/adr/ADR-0015-netkingdom-railiance-workload-packaging-and-relational-platform.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Workload packaging." + }, + { + "source_repo": "railiance-infra", + "source_path": "docs/adr/ADR-005-k3s-api-tunnel-only.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "k3s API exposure binds the fleet." + }, + { + "source_repo": "coulomb-social", + "source_path": "docs/adr/ADR-0001-netkingdom-identity.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Identity choice for the social surface." + }, + { + "source_repo": "coulomb-social", + "source_path": "docs/adr/ADR-0003-page-centric-markdown-sor.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Content SoR." + }, + { + "source_repo": "coulomb-social", + "source_path": "docs/adr/ADR-0004-content-plane-thin-git-upgrades.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Content plane upgrades." + }, + { + "source_repo": "coulomb-loop", + "source_path": "docs/adr/ADR-001-workplan-prefix.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Workplan prefix convention used fleet-wide." + }, + { + "source_repo": "kaizen-agentic", + "source_path": "docs/adr/ADR-001-workplan-convention.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Workplan convention consumed by agents." + }, + { + "source_repo": "glas-harness", + "source_path": "docs/adr/ADR-001-rein-harness-family.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Harness family routing." + }, + { + "source_repo": "glas-harness", + "source_path": "docs/adr/ADR-003-scheduling-and-blueprint-sourcing-stay-rein-local.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Scheduling locality." + }, + { + "source_repo": "rein-aharness", + "source_path": "docs/adr/ADR-001-agent-harness-architecture.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Shared harness, instances in consumers." + }, + { + "source_repo": "the-custodian", + "source_path": "canon/constitution/custodian_constitution_v0.1.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Estate constitution." + }, + { + "source_repo": "the-custodian", + "source_path": "canon/constitution/bootstrap-protocol_v0.1.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Bootstrap protocol." + }, + { + "source_repo": "the-custodian", + "source_path": "canon/standards/work-record-types_v0.1.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Work-record type registry." + }, + { + "source_repo": "the-custodian", + "source_path": "canon/standards/workplan-terminology-fleet_v0.1.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Fleet workplan terminology." + }, + { + "source_repo": "the-custodian", + "source_path": "canon/standards/repo-classification-standard_v1.0.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Repo classification." + }, + { + "source_repo": "the-custodian", + "source_path": "canon/standards/project-repository-flavor_v0.1.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "prj- flavor." + }, + { + "source_repo": "the-custodian", + "source_path": "canon/standards/contribution-convention_v0.1.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Contribution convention." + }, + { + "source_repo": "the-custodian", + "source_path": "canon/standards/autonomy-lanes_v0.1.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "Autonomy lanes." + }, + { + "source_repo": "the-custodian", + "source_path": "canon/standards/sbom-convention_v0.1.md", + "proposed_disposition": "publish", + "conflict_kinds": [], + "successor": "", + "review_notes": "SBOM convention." + }, + { + "source_repo": "coulomb-loop", + "source_path": "docs/adr/ADR-002-customer-supplier-boundary.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Engagement boundary for the loop product." + }, + { + "source_repo": "coulomb-loop", + "source_path": "docs/adr/ADR-003-cadence-ramp-policy.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Loop cadence policy." + }, + { + "source_repo": "coulomb-loop", + "source_path": "docs/adr/ADR-004-repo-rotation-on-diminishing-returns.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Loop rotation heuristic." + }, + { + "source_repo": "kaizen-agentic", + "source_path": "docs/adr/ADR-002-project-memory-convention.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Kaizen project memory." + }, + { + "source_repo": "kaizen-agentic", + "source_path": "docs/adr/ADR-003-protocols-artifact-convention.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Kaizen protocols artifact." + }, + { + "source_repo": "kaizen-agentic", + "source_path": "docs/adr/ADR-004-project-metrics-convention.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Kaizen metrics." + }, + { + "source_repo": "kaizen-agentic", + "source_path": "docs/adr/ADR-005-scheduled-agent-execution.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Kaizen scheduler." + }, + { + "source_repo": "kaizen-agentic", + "source_path": "docs/adr/ADR-006-customer-engagement-convention.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Kaizen engagement." + }, + { + "source_repo": "kaizen-agentic", + "source_path": "docs/adr/ADR-007-forward-deployed-engagement-convention.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Kaizen forward-deployed engagement." + }, + { + "source_repo": "the-custodian", + "source_path": "canon/standards/coulombcore-production-freeze_v0.1.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Time-boxed freeze, not standing architecture." + }, + { + "source_repo": "the-custodian", + "source_path": "canon/standards/credential-management_v0.1.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Superseded in spirit by net-kingdom credential standard; leave local until owner marks successor." + }, + { + "source_repo": "the-custodian", + "source_path": "canon/standards/business-app-service-contract_v0.1.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "App contract; owner should confirm governing vs local." + }, + { + "source_repo": "the-custodian", + "source_path": "canon/standards/federated-organization-standard_v1.0.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Draft; not yet governing." + }, + { + "source_repo": "the-custodian", + "source_path": "canon/standards/orthogonal-architecture_v1.0.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Draft OAS." + }, + { + "source_repo": "the-custodian", + "source_path": "canon/standards/orthogonal-architecture-schema_v1.0.1.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Schema companion to draft OAS." + }, + { + "source_repo": "the-custodian", + "source_path": "canon/standards/privileged-execution-control-schema_v0.2.1.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Schema companion." + }, + { + "source_repo": "the-custodian", + "source_path": "canon/standards/privileged-execution-control-schema-cicd_v0.2.1.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Schema companion." + }, + { + "source_repo": "the-custodian", + "source_path": "canon/standards/privileged-execution-control-schema-kubernetes-rbac_v0.2.1.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Schema companion." + }, + { + "source_repo": "the-custodian", + "source_path": "canon/standards/privileged-execution-control-schema-os-sudo_v0.2.1.md", + "proposed_disposition": "local", + "conflict_kinds": [], + "successor": "", + "review_notes": "Schema companion." } ] } diff --git a/publication.json b/publication.json index e2804ca..318bce9 100644 --- a/publication.json +++ b/publication.json @@ -33,6 +33,9 @@ }, "ops-warden": { "path": "../ops-warden" + }, + "railiance-platform": { + "path": "../railiance-platform" } }, "documents": [ @@ -239,6 +242,110 @@ "canonical_path": "adr/ops-warden-implement-narrowly/v1/index.html", "revision_path": "adr/ops-warden-implement-narrowly/v1/revisions/{revision}/index.html", "review_interval": "6m" + }, + { + "id": "CUST-ADR-001", + "source_repo": "the-custodian", + "source_path": "canon/architecture/adr-001-workplans-as-repo-artefacts.md", + "canonical_path": "adr/custodian-workplans-as-repo-artefacts/v1/index.html", + "revision_path": "adr/custodian-workplans-as-repo-artefacts/v1/revisions/{revision}/index.html", + "review_interval": "6m" + }, + { + "id": "CUST-ADR-002", + "source_repo": "the-custodian", + "source_path": "canon/architecture/adr-002-custodian-agent-runtime-design.md", + "canonical_path": "adr/custodian-agent-runtime/v1/index.html", + "revision_path": "adr/custodian-agent-runtime/v1/revisions/{revision}/index.html", + "review_interval": "6m" + }, + { + "id": "CUST-ADR-003", + "source_repo": "the-custodian", + "source_path": "canon/architecture/adr-003-materialized-derived-state.md", + "canonical_path": "adr/custodian-materialized-derived-state/v1/index.html", + "revision_path": "adr/custodian-materialized-derived-state/v1/revisions/{revision}/index.html", + "review_interval": "6m" + }, + { + "id": "CUST-ADR-004", + "source_repo": "the-custodian", + "source_path": "canon/architecture/adr-004-connectivity-first-network-posture.md", + "canonical_path": "adr/custodian-connectivity-first/v1/index.html", + "revision_path": "adr/custodian-connectivity-first/v1/revisions/{revision}/index.html", + "review_interval": "6m" + }, + { + "id": "CUST-ADR-005", + "source_repo": "the-custodian", + "source_path": "canon/architecture/adr-005-cross-repo-workplans-project-repos.md", + "canonical_path": "adr/custodian-cross-repo-workplans/v1/index.html", + "revision_path": "adr/custodian-cross-repo-workplans/v1/revisions/{revision}/index.html", + "review_interval": "6m" + }, + { + "id": "CUST-ADR-006", + "source_repo": "the-custodian", + "source_path": "canon/architecture/adr-006-canon-federation-concept-ownership.md", + "canonical_path": "adr/custodian-canon-federation/v1/index.html", + "revision_path": "adr/custodian-canon-federation/v1/revisions/{revision}/index.html", + "review_interval": "6m" + }, + { + "id": "CUST-ADR-007", + "source_repo": "the-custodian", + "source_path": "canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md", + "canonical_path": "adr/custodian-workplan-identity/v1/index.html", + "revision_path": "adr/custodian-workplan-identity/v1/revisions/{revision}/index.html", + "review_interval": "6m" + }, + { + "id": "CUST-ADR-010", + "source_repo": "the-custodian", + "source_path": "canon/architecture/adr-010-hub-authority-and-local-cache-model.md", + "canonical_path": "adr/custodian-hub-authority/v1/index.html", + "revision_path": "adr/custodian-hub-authority/v1/revisions/{revision}/index.html", + "review_interval": "6m" + }, + { + "id": "CUST-ADR-011", + "source_repo": "the-custodian", + "source_path": "canon/architecture/adr-011-federated-namespaces-and-reconciliation-limits.md", + "canonical_path": "adr/custodian-federated-namespaces/v1/index.html", + "revision_path": "adr/custodian-federated-namespaces/v1/revisions/{revision}/index.html", + "review_interval": "6m" + }, + { + "id": "RPLAT-ADR-0001", + "source_repo": "railiance-platform", + "source_path": "docs/adr/ADR-0001-s3-platform-service-boundary.md", + "canonical_path": "adr/railiance-s3-platform-service-boundary/v1/index.html", + "revision_path": "adr/railiance-s3-platform-service-boundary/v1/revisions/{revision}/index.html", + "review_interval": "6m" + }, + { + "id": "RPLAT-ADR-0002", + "source_repo": "railiance-platform", + "source_path": "docs/adr/ADR-0002-placement-policy-ownership.md", + "canonical_path": "adr/railiance-placement-policy-ownership/v1/index.html", + "revision_path": "adr/railiance-placement-policy-ownership/v1/revisions/{revision}/index.html", + "review_interval": "6m" + }, + { + "id": "RPLAT-ADR-0003", + "source_repo": "railiance-platform", + "source_path": "docs/adr/ADR-0003-decisions-live-in-the-repo.md", + "canonical_path": "adr/railiance-decisions-live-in-the-repo/v1/index.html", + "revision_path": "adr/railiance-decisions-live-in-the-repo/v1/revisions/{revision}/index.html", + "review_interval": "6m" + }, + { + "id": "netkingdom-iam-profile-v0.3", + "source_repo": "net-kingdom", + "source_path": "canon/standards/iam-profile_v0.3.md", + "canonical_path": "standards/iam-profile/v0.3/index.html", + "revision_path": "standards/iam-profile/v0.3/revisions/{revision}/index.html", + "review_interval": "6m" } ] } diff --git a/source-inventory.json b/source-inventory.json index 749fb03..4adfd21 100644 --- a/source-inventory.json +++ b/source-inventory.json @@ -254,8 +254,8 @@ "source_repo": "net-kingdom" }, { - "disposition": "metadata-pending", - "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "disposition": "published", + "reason": "Published through an explicit publication.json document entry.", "source_path": "canon/standards/iam-profile_v0.3.md", "source_repo": "net-kingdom" }, @@ -488,20 +488,20 @@ "source_repo": "railiance-master" }, { - "disposition": "metadata-pending", - "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "disposition": "published", + "reason": "Published through an explicit publication.json document entry.", "source_path": "docs/adr/ADR-0001-s3-platform-service-boundary.md", "source_repo": "railiance-platform" }, { - "disposition": "metadata-pending", - "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "disposition": "published", + "reason": "Published through an explicit publication.json document entry.", "source_path": "docs/adr/ADR-0002-placement-policy-ownership.md", "source_repo": "railiance-platform" }, { - "disposition": "metadata-pending", - "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "disposition": "published", + "reason": "Published through an explicit publication.json document entry.", "source_path": "docs/adr/ADR-0003-decisions-live-in-the-repo.md", "source_repo": "railiance-platform" }, @@ -560,44 +560,44 @@ "source_repo": "target-revenue" }, { - "disposition": "metadata-pending", - "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "disposition": "published", + "reason": "Published through an explicit publication.json document entry.", "source_path": "canon/architecture/adr-001-workplans-as-repo-artefacts.md", "source_repo": "the-custodian" }, { - "disposition": "metadata-pending", - "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "disposition": "published", + "reason": "Published through an explicit publication.json document entry.", "source_path": "canon/architecture/adr-002-custodian-agent-runtime-design.md", "source_repo": "the-custodian" }, { - "disposition": "metadata-pending", - "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "disposition": "published", + "reason": "Published through an explicit publication.json document entry.", "source_path": "canon/architecture/adr-003-materialized-derived-state.md", "source_repo": "the-custodian" }, { - "disposition": "metadata-pending", - "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "disposition": "published", + "reason": "Published through an explicit publication.json document entry.", "source_path": "canon/architecture/adr-004-connectivity-first-network-posture.md", "source_repo": "the-custodian" }, { - "disposition": "metadata-pending", - "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "disposition": "published", + "reason": "Published through an explicit publication.json document entry.", "source_path": "canon/architecture/adr-005-cross-repo-workplans-project-repos.md", "source_repo": "the-custodian" }, { - "disposition": "metadata-pending", - "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "disposition": "published", + "reason": "Published through an explicit publication.json document entry.", "source_path": "canon/architecture/adr-006-canon-federation-concept-ownership.md", "source_repo": "the-custodian" }, { - "disposition": "metadata-pending", - "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "disposition": "published", + "reason": "Published through an explicit publication.json document entry.", "source_path": "canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md", "source_repo": "the-custodian" }, @@ -608,14 +608,14 @@ "source_repo": "the-custodian" }, { - "disposition": "metadata-pending", - "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "disposition": "published", + "reason": "Published through an explicit publication.json document entry.", "source_path": "canon/architecture/adr-010-hub-authority-and-local-cache-model.md", "source_repo": "the-custodian" }, { - "disposition": "metadata-pending", - "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "disposition": "published", + "reason": "Published through an explicit publication.json document entry.", "source_path": "canon/architecture/adr-011-federated-namespaces-and-reconciliation-limits.md", "source_repo": "the-custodian" }, @@ -625,6 +625,54 @@ "source_path": "canon/architecture/coulomb-estate_v0.1.md", "source_repo": "the-custodian" }, + { + "disposition": "unsupported-format", + "reason": "Inventoried governing source is not Markdown and has no renderer yet.", + "source_path": "canon/architecture/infospace/.gitignore", + "source_repo": "the-custodian" + }, + { + "disposition": "metadata-pending", + "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "source_path": "canon/architecture/infospace/discipline/arc42.md", + "source_repo": "the-custodian" + }, + { + "disposition": "metadata-pending", + "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "source_path": "canon/architecture/infospace/entities/coulomb-estate.md", + "source_repo": "the-custodian" + }, + { + "disposition": "metadata-pending", + "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "source_path": "canon/architecture/infospace/entities/net-kingdom.md", + "source_repo": "the-custodian" + }, + { + "disposition": "metadata-pending", + "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "source_path": "canon/architecture/infospace/entities/policy-nexus.md", + "source_repo": "the-custodian" + }, + { + "disposition": "metadata-pending", + "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "source_path": "canon/architecture/infospace/entities/railiance.md", + "source_repo": "the-custodian" + }, + { + "disposition": "metadata-pending", + "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", + "source_path": "canon/architecture/infospace/entities/state-hub.md", + "source_repo": "the-custodian" + }, + { + "disposition": "unsupported-format", + "reason": "Inventoried governing source is not Markdown and has no renderer yet.", + "source_path": "canon/architecture/infospace/infospace.yaml", + "source_repo": "the-custodian" + }, { "disposition": "metadata-pending", "reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.", diff --git a/workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md b/workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md index 45f3462..22271d6 100644 --- a/workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md +++ b/workplans/POLICY-NEXUS-WP-0003-adr-review-cleanup-publish.md @@ -195,7 +195,7 @@ on chapter 9 (now present on the estate stub; re-check in T04). ```task id: POLICY-NEXUS-WP-0003-T04 -status: progress +status: done priority: high ``` @@ -220,6 +220,10 @@ copies. Publish (after prefix/metadata packets): estate ADRs 001–007 and Profile v0.3. Remainder still `unreviewed`. Kind 5 against the estate chapter 9: the listed estate ADRs match; no miss on that document. +Completed 2026-08-19. Remaining rows are classified: fleet-binding +records `publish`, product-local notes `local`, templates and draft +companions `local`. Unsupported formats stay inventoried, not published. + ### T05 — Cleanup packets ```task @@ -276,7 +280,7 @@ publication-ready) are registered. ```task id: POLICY-NEXUS-WP-0003-T07 -status: todo +status: progress priority: medium ``` @@ -287,6 +291,10 @@ unresolved `conflict` rows as current. This is a PR in the owning repo of the arc42 document, same as T05. Depends on WP-0002-T04/T05 and on this workplan's T04. +2026-08-19: first-wave chapter 9 lists CUST-ADR-001–011, published +Railiance/NetKingdom/activity-core/ops-warden/platform ADRs, and keeps +hosts/infra conflicts out. Stubs bumped to draft-2. + ## Sequencing T01 → T02 → T03 and T04 (T04's kind-5 slice waits on WP-0002-T04).