docs(canon): reconcile workload and tenant grouping semantics
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a02929-244b-7391-b933-c04010e8eedb
This commit is contained in:
parent
ad2057acff
commit
bee22db620
21 changed files with 1118 additions and 59 deletions
|
|
@ -1,3 +1,15 @@
|
|||
---
|
||||
id: NK-ADR-0006
|
||||
type: architecture-decision-record
|
||||
title: "Recursive Multi-Tenant Identity and Authorization Architecture"
|
||||
status: accepted
|
||||
owner: net-kingdom
|
||||
revision: "1"
|
||||
decided: "2026-05-17"
|
||||
last_reviewed: "2026-08-22"
|
||||
review_interval: 12m
|
||||
---
|
||||
|
||||
# ADR-0006 - Recursive Multi-Tenant Identity and Authorization Architecture
|
||||
|
||||
**Status:** Accepted
|
||||
|
|
|
|||
|
|
@ -1,3 +1,15 @@
|
|||
---
|
||||
id: NK-ADR-0007
|
||||
type: architecture-decision-record
|
||||
title: "Security Orchestration Boundary"
|
||||
status: accepted
|
||||
owner: net-kingdom
|
||||
revision: "1"
|
||||
decided: "2026-05-18"
|
||||
last_reviewed: "2026-08-22"
|
||||
review_interval: 12m
|
||||
---
|
||||
|
||||
# ADR-0007 - Security Orchestration Boundary
|
||||
|
||||
**Status:** Accepted
|
||||
|
|
|
|||
|
|
@ -1,3 +1,15 @@
|
|||
---
|
||||
id: NK-ADR-0008
|
||||
type: architecture-decision-record
|
||||
title: "Object Storage STS Credential Vending Boundary"
|
||||
status: accepted
|
||||
owner: net-kingdom
|
||||
revision: "1"
|
||||
decided: "2026-05-18"
|
||||
last_reviewed: "2026-08-22"
|
||||
review_interval: 12m
|
||||
---
|
||||
|
||||
# ADR-0008 - Object Storage STS Credential Vending Boundary
|
||||
|
||||
**Status:** Accepted
|
||||
|
|
|
|||
|
|
@ -1,3 +1,15 @@
|
|||
---
|
||||
id: NK-ADR-0010
|
||||
type: architecture-decision-record
|
||||
title: "Orchestration vs Dependency, and Self-Coherent Intent"
|
||||
status: accepted
|
||||
owner: net-kingdom
|
||||
revision: "1"
|
||||
decided: "2026-05-21"
|
||||
last_reviewed: "2026-08-22"
|
||||
review_interval: 12m
|
||||
---
|
||||
|
||||
# ADR-0010 - Orchestration vs Dependency, and Self-Coherent Intent
|
||||
|
||||
**Status:** Accepted (repo classification subject to ongoing refinement)
|
||||
|
|
|
|||
|
|
@ -1,3 +1,15 @@
|
|||
---
|
||||
id: NK-ADR-0011
|
||||
type: architecture-decision-record
|
||||
title: "NetKingdom IAM Profile Ownership And Version Governance"
|
||||
status: accepted
|
||||
owner: net-kingdom
|
||||
revision: "1"
|
||||
decided: "2026-05-22"
|
||||
last_reviewed: "2026-08-22"
|
||||
review_interval: 12m
|
||||
---
|
||||
|
||||
# ADR-0011 - NetKingdom IAM Profile Ownership And Version Governance
|
||||
|
||||
**Status:** Accepted
|
||||
|
|
|
|||
|
|
@ -1,3 +1,15 @@
|
|||
---
|
||||
id: NK-ADR-0012
|
||||
type: architecture-decision-record
|
||||
title: "Playbook Capability Contract Ownership"
|
||||
status: accepted
|
||||
owner: net-kingdom
|
||||
revision: "1"
|
||||
decided: "2026-05-22"
|
||||
last_reviewed: "2026-08-22"
|
||||
review_interval: 12m
|
||||
---
|
||||
|
||||
# ADR-0012 - Playbook Capability Contract Ownership
|
||||
|
||||
**Status:** Accepted
|
||||
|
|
|
|||
|
|
@ -1,7 +1,20 @@
|
|||
---
|
||||
id: NK-ADR-0013
|
||||
type: architecture-decision-record
|
||||
title: "Tenant Onboarding Grouping Taxonomy"
|
||||
status: accepted
|
||||
owner: net-kingdom
|
||||
revision: "2"
|
||||
decided: "2026-07-23"
|
||||
last_reviewed: "2026-08-22"
|
||||
review_interval: 12m
|
||||
---
|
||||
|
||||
# ADR-0013 - Tenant Onboarding Grouping Taxonomy
|
||||
|
||||
**Status:** Accepted
|
||||
**Date:** 2026-07-23
|
||||
**Amended:** 2026-08-22 (current classification versus historical identifier segment)
|
||||
**Deciders:** Bernd Worsch, Codex
|
||||
|
||||
## Context
|
||||
|
|
@ -54,12 +67,26 @@ association - a legal association of people
|
|||
agentic - financially enabled AI entities
|
||||
```
|
||||
|
||||
This grouping is deliberately **orthogonal to capability role**
|
||||
(`PLTF`/`IAM`/`VEN`/`CUS`, still unratified): the grouping describes *what
|
||||
kind of entity a tenant is and how it was onboarded*; role describes *what
|
||||
it does on the platform*. Both may need to be carried as tenant metadata,
|
||||
but never conflated into one identifier segment — that conflation is exactly
|
||||
what this ADR avoids.
|
||||
The taxonomy has two deliberately different uses:
|
||||
|
||||
- At creation, the identifier's grouping segment records the tenant's
|
||||
onboarding-time classification. The complete identifier is immutable, so
|
||||
this segment is historical after creation.
|
||||
- The tenant record's `grouping` field records current classification. It may
|
||||
change as the entity changes and is authoritative for present-day policy,
|
||||
including guardrails and spend ceilings.
|
||||
|
||||
No consumer may parse the identifier's middle segment and treat it as current
|
||||
grouping. Consumers needing current grouping MUST read it from `tenant-engine`.
|
||||
Identifier creation still validates the segment against this vocabulary;
|
||||
historical does not mean free-form or optional.
|
||||
|
||||
Grouping is deliberately **orthogonal to capability role**
|
||||
(`PLTF`/`IAM`/`VEN`/`CUS`, subsequently ratified by ADR-0014): grouping
|
||||
describes *what kind of entity a tenant is and its current onboarding-risk
|
||||
classification*; role describes *what it does on the platform*. Both are
|
||||
carried as tenant metadata, but never conflated into the immutable identifier
|
||||
segment — that conflation is exactly what this ADR avoids.
|
||||
|
||||
`tenant:platform` and `tenant:coulomb` remain **reserved, ungrouped
|
||||
identifiers outside this taxonomy**: `tenant:platform` is the control-plane
|
||||
|
|
@ -101,10 +128,15 @@ section — not a new versioned profile document.
|
|||
already reflects this decision (`tenant:friendly:binky`).
|
||||
- Future tenant onboarding work should classify a tenant against this list
|
||||
before minting an identifier, rather than reaching for a role word.
|
||||
- The capability-role model (`PLTF`/`IAM`/`VEN`/`CUS`) remains a separate,
|
||||
still-unratified dimension; this ADR does not ratify that model, only
|
||||
avoids colliding with it. If/when it is ratified, role metadata should be
|
||||
carried alongside — not instead of — the grouping segment decided here.
|
||||
- Tenant identifiers never change when current grouping changes. The middle
|
||||
segment is creation-time history; `tenant-engine` is authoritative for the
|
||||
current grouping value.
|
||||
- Policy and commercial consumers, including spend-ceiling resolution, MUST
|
||||
query `tenant-engine` and MUST NOT derive current grouping by splitting a
|
||||
tenant identifier.
|
||||
- The capability-role model (`PLTF`/`IAM`/`VEN`/`CUS`) remains a separate
|
||||
dimension, now ratified by ADR-0014. Role metadata is carried alongside —
|
||||
not instead of — current grouping and the historical identifier segment.
|
||||
- `tenant:platform` and `tenant:coulomb` are reserved outside the taxonomy,
|
||||
pending Bernd's explicit confirmation (see Decision).
|
||||
|
||||
|
|
@ -138,6 +170,8 @@ resolved before the first non-Coulomb tenant goes live, not after.
|
|||
reviewable change).
|
||||
- Confirm the `tenant:platform`/`tenant:coulomb` reserved/ungrouped
|
||||
treatment explicitly.
|
||||
- If/when the `PLTF`/`IAM`/`VEN`/`CUS` capability-role model is ratified,
|
||||
define how role metadata is carried alongside the grouping segment
|
||||
decided here.
|
||||
- ADR-0014 and the Tenant Engine Boundary Contract define how capability-role
|
||||
metadata is carried alongside grouping.
|
||||
- Keep `tenant-engine`'s identifier parser vocabulary-validating for creation
|
||||
and lookup compatibility, but do not expose parsed grouping as current
|
||||
classification.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,15 @@
|
|||
---
|
||||
id: NK-ADR-0014
|
||||
type: architecture-decision-record
|
||||
title: "Tenant Capability Roles, Carrying Mechanism, and Tenant-Engine Ownership"
|
||||
status: accepted
|
||||
owner: net-kingdom
|
||||
revision: "1"
|
||||
decided: "2026-07-23"
|
||||
last_reviewed: "2026-08-22"
|
||||
review_interval: 12m
|
||||
---
|
||||
|
||||
# ADR-0014 - Tenant Capability Roles, Carrying Mechanism, and Tenant-Engine Ownership
|
||||
|
||||
**Status:** Accepted
|
||||
|
|
|
|||
|
|
@ -1,3 +1,15 @@
|
|||
---
|
||||
id: NK-ADR-0015
|
||||
type: architecture-decision-record
|
||||
title: "NetKingdom Railiance Workload Packaging and Relational Platform"
|
||||
status: accepted
|
||||
owner: net-kingdom
|
||||
revision: "1"
|
||||
decided: "2026-08-11"
|
||||
last_reviewed: "2026-08-22"
|
||||
review_interval: 12m
|
||||
---
|
||||
|
||||
# ADR-0015 - NetKingdom Railiance Workload Packaging and Relational Platform
|
||||
|
||||
**Status:** Accepted
|
||||
|
|
|
|||
109
docs/reef-posture-provider-contract.md
Normal file
109
docs/reef-posture-provider-contract.md
Normal file
|
|
@ -0,0 +1,109 @@
|
|||
# Reef posture-provider contract
|
||||
|
||||
Status: proposal for `repo-manager` agreement under `NK-WP-0027-T02`
|
||||
|
||||
Date: 2026-08-22
|
||||
|
||||
Canon owner: `net-kingdom`
|
||||
|
||||
Reef vocabulary and declaration owner: `repo-manager` / `railiance-master`
|
||||
|
||||
## Purpose
|
||||
|
||||
A reef states where workloads may be placed and which residual substrate risk
|
||||
has been accepted. It is not a `P` level. It can nevertheless bound a posture
|
||||
axis: the current single-member `reef-railiance` can never make V2 failover
|
||||
reachable, regardless of how many replicas a workload declares.
|
||||
|
||||
This proposal extends Tenancy Posture Decision 5.5's provider shape to reefs
|
||||
without moving reef vocabulary into NetKingdom. The block belongs in the
|
||||
authoritative `declarations/reef.yaml`; it does not create a second reef file or
|
||||
duplicate the derived `bound_rapps` projection.
|
||||
|
||||
## Proposed declaration block
|
||||
|
||||
```yaml
|
||||
posture_provider:
|
||||
framework: netkingdom-tenancy-posture
|
||||
reviewed: "2026-08-22"
|
||||
review_due: "2027-02-22"
|
||||
axes:
|
||||
V:
|
||||
available: 0
|
||||
maximum: 1
|
||||
conditions:
|
||||
- A bound workload documents and exercises restart or recreation recovery in this failure domain.
|
||||
- The workload names every synchronous dependency used by the claimed operation.
|
||||
evidence:
|
||||
- evidence/verification/rail-runtime-2026-08-21.json
|
||||
- evidence/admission/rail-kubernetes-baseline.json
|
||||
reason: One observed member carries the control plane, etcd, and workloads; no automated failover is reachable.
|
||||
```
|
||||
|
||||
The `reef-railiance` values are deliberately conservative:
|
||||
|
||||
- `available: 0` means the reef offers no unconditional, reusable recovery
|
||||
guarantee to every bound workload today. A Ready node is not recovery
|
||||
evidence.
|
||||
- `maximum: 1` means a named workload can reach V1 by satisfying and evidencing
|
||||
the restart/recreate conditions. One failure domain makes V2 unreachable.
|
||||
|
||||
The owner may raise `available` when the reef publishes a reusable recovery
|
||||
guarantee that consumers can cite. Adding independent members and an exercised
|
||||
failover path may raise `maximum`; topology alone does not.
|
||||
|
||||
## Semantics
|
||||
|
||||
Each declared axis contains:
|
||||
|
||||
| Field | Meaning |
|
||||
| --- | --- |
|
||||
| `available` | Highest level the provider guarantees unconditionally to every binding in scope, with current evidence. |
|
||||
| `maximum` | Highest level a named consumer can reach after satisfying the listed conditions. |
|
||||
| `conditions` | Consumer or binding work required above `available`; empty only when `available == maximum`. |
|
||||
| `evidence` | Source-linked, current artifacts supporting the provider facts. |
|
||||
| `reason` | Why the ceiling exists, especially when structural or accepted. |
|
||||
|
||||
A reef declares only axes it materially bounds. A compute reef normally
|
||||
declares `V`; it does not declare `P` merely because data-bearing workloads sit
|
||||
on it. A provider-delegated storage reef may bound `P`, `R`, or `V`, but only
|
||||
where the substrate contract actually makes those properties reachable.
|
||||
|
||||
`available` and `maximum` use the axis vocabulary from
|
||||
`tenancy-posture_v0.1`. `available` MUST NOT exceed `maximum`. Review dates and
|
||||
evidence discipline follow Decisions 5.4, 5.5, and §13.
|
||||
|
||||
## Mechanical reconciliation
|
||||
|
||||
For each workload operation and each bound reef:
|
||||
|
||||
1. Resolve the reef from the workload's authoritative placement declaration.
|
||||
Missing or conflicting placement is `unknown`; do not select a default reef.
|
||||
2. Load the reef's `posture_provider` block from `declarations/reef.yaml`.
|
||||
3. Reject a workload claim above the reef's `maximum`.
|
||||
4. For a claim above `available`, require machine-readable evidence that every
|
||||
listed condition is satisfied for that workload and operation.
|
||||
5. Compose `V` with every synchronous provider using Decision 4.6.1's minimum
|
||||
rule. A reef ceiling is one input, not the whole availability claim.
|
||||
6. Emit the reef declaration revision and evidence references in the
|
||||
reconciliation result so the decision is reproducible.
|
||||
|
||||
The result is one of `satisfied`, `unsatisfied`, or `unknown`. `unknown` covers
|
||||
an absent provider block, unresolved reef binding, stale review, missing
|
||||
evidence, or an unrecognised axis value. It is never converted to a permissive
|
||||
ceiling.
|
||||
|
||||
## Ownership boundary
|
||||
|
||||
- `net-kingdom` owns the meaning of provider reachability and the `P`/`V`
|
||||
composition rules.
|
||||
- `repo-manager` / `railiance-master` owns whether and how this block is added
|
||||
to the reef schema.
|
||||
- Each `reef-*` repo owns its values, evidence, and review.
|
||||
- The workload owner owns its claim and evidence that provider conditions are
|
||||
met.
|
||||
- The reconciler reports; it does not manufacture acceptance or posture.
|
||||
|
||||
T03 may implement the join only after `repo-manager` agrees the authoritative
|
||||
field name and carrier. The semantics above are the canon-side acceptance
|
||||
criteria; the exact reef-schema spelling remains the reef owner's decision.
|
||||
Loading…
Add table
Add a link
Reference in a new issue